@juvantlabs/m365-graph-mcp-server 0.1.0

package/dist/tools/upload_file.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tool: m365-graph:upload_file
+ *
+ * Upload a local file to a drive. Auto-routes between two paths based
+ * on file size:
+ *   - ≤ 4 MB → single PUT to `/items/{parent}:/{name}:/content`
+ *   - > 4 MB → resumable upload session via OneDriveLargeFileUploadTask
+ *     (10 MB chunks, automatic resume on transient errors)
+ *
+ * Required Graph scope: `Files.ReadWrite` (delegated). Writes to the
+ * cloud side. Reads from the caller-supplied `local_path` on the
+ * server's filesystem.
+ *
+ * Trust note: the agent supplies `local_path`. The MCP server runs as
+ * the user; the user trusts the agent. There's no server-side path
+ * sandbox for *uploads* (unlike downloads, which we sandbox to a
+ * known dir): an upload tool that refused arbitrary paths would be
+ * useless for the canonical "upload this file the user prepared"
+ * workflow. The absolute path is logged to stderr so operators can
+ * review via the MCP server logs.
+ *
+ * Size cap: 200 MB (handbook spec § Performance). Refused pre-read.
+ *
+ * Conflict behavior is parametric:
+ *   - `fail`    (default) — refuse if a file with that name exists
+ *   - `replace` — overwrite the existing file (creates a new version)
+ *   - `rename`  — let Graph append a numeric suffix
+ */
+import type { Tool } from "../types/tool.js";
+export declare const MAX_FILE_SIZE: number;
+/**
+ * Throw if the file size exceeds the configured maximum. Extracted so
+ * this defense-in-depth check can be unit-tested independently of the
+ * actual fs + Graph integration in the handler.
+ */
+export declare function checkSizeCap(size: number): void;
+export declare const uploadFileTool: Tool;
+//# sourceMappingURL=upload_file.d.ts.map

package/dist/tools/upload_file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_file.d.ts","sourceRoot":"","sources":["../../src/tools/upload_file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAmBH,OAAO,KAAK,EAAE,IAAI,EAA6C,MAAM,kBAAkB,CAAC;AAGxF,eAAO,MAAM,aAAa,QAAoB,CAAC;AAG/C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAM/C;AAsJD,eAAO,MAAM,cAAc,EAAE,IAA8B,CAAC"}

package/dist/tools/upload_file.js

@@ -0,0 +1,152 @@
+/**
+ * Tool: m365-graph:upload_file
+ *
+ * Upload a local file to a drive. Auto-routes between two paths based
+ * on file size:
+ *   - ≤ 4 MB → single PUT to `/items/{parent}:/{name}:/content`
+ *   - > 4 MB → resumable upload session via OneDriveLargeFileUploadTask
+ *     (10 MB chunks, automatic resume on transient errors)
+ *
+ * Required Graph scope: `Files.ReadWrite` (delegated). Writes to the
+ * cloud side. Reads from the caller-supplied `local_path` on the
+ * server's filesystem.
+ *
+ * Trust note: the agent supplies `local_path`. The MCP server runs as
+ * the user; the user trusts the agent. There's no server-side path
+ * sandbox for *uploads* (unlike downloads, which we sandbox to a
+ * known dir): an upload tool that refused arbitrary paths would be
+ * useless for the canonical "upload this file the user prepared"
+ * workflow. The absolute path is logged to stderr so operators can
+ * review via the MCP server logs.
+ *
+ * Size cap: 200 MB (handbook spec § Performance). Refused pre-read.
+ *
+ * Conflict behavior is parametric:
+ *   - `fail`    (default) — refuse if a file with that name exists
+ *   - `replace` — overwrite the existing file (creates a new version)
+ *   - `rename`  — let Graph append a numeric suffix
+ */
+import fs from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import path from "node:path";
+import { OneDriveLargeFileUploadTask, StreamUpload, } from "@microsoft/microsoft-graph-client";
+import { validateOptionalEnum, validateOptionalString, validateRequiredString, } from "../types/validators.js";
+const SMALL_FILE_CAP = 4 * 1024 * 1024; // 4 MB — single-PUT threshold per Graph docs
+export const MAX_FILE_SIZE = 200 * 1024 * 1024; // 200 MB hard cap (handbook spec)
+const LARGE_FILE_RANGE = 10 * 1024 * 1024; // 10 MB chunks for resumable
+/**
+ * Throw if the file size exceeds the configured maximum. Extracted so
+ * this defense-in-depth check can be unit-tested independently of the
+ * actual fs + Graph integration in the handler.
+ */
+export function checkSizeCap(size) {
+    if (size > MAX_FILE_SIZE) {
+        throw new Error(`File size (${size} bytes) exceeds the 200 MB cap. Refusing to upload.`);
+    }
+}
+const CONFLICT_BEHAVIORS = ["fail", "replace", "rename"];
+const definition = {
+    name: "m365-graph:upload_file",
+    description: "Upload a local file to a drive (OneDrive primary by default; SharePoint via drive_id). Auto-routes between single PUT (≤ 4 MB) and resumable upload (> 4 MB, 10 MB chunks) based on file size. Default conflict behavior is 'fail' — set to 'replace' or 'rename' to overwrite or auto-rename. 200 MB hard cap.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            local_path: {
+                type: "string",
+                description: "Absolute or relative path to the local file to upload. Resolved to absolute before reading.",
+            },
+            drive_id: {
+                type: "string",
+                description: "Optional drive ID. Defaults to the user's primary OneDrive.",
+            },
+            parent_item_id: {
+                type: "string",
+                description: "Optional folder ID to upload INTO. Defaults to the drive root. Get from list_items.",
+            },
+            name: {
+                type: "string",
+                description: "Optional name for the uploaded file. Defaults to the basename of local_path.",
+            },
+            conflict_behavior: {
+                type: "string",
+                enum: ["fail", "replace", "rename"],
+                description: "What to do if a file with this name already exists. Default: 'fail'.",
+            },
+        },
+        required: ["local_path"],
+    },
+};
+function summarizeUploadedItem(item) {
+    return {
+        id: String(item.id ?? ""),
+        name: String(item.name ?? ""),
+        size: Number(item.size ?? 0),
+        webUrl: String(item.webUrl ?? ""),
+    };
+}
+const handler = async (graph, args) => {
+    const localPathRaw = validateRequiredString(args.local_path, "local_path");
+    const localPath = path.resolve(localPathRaw);
+    const driveId = validateOptionalString(args.drive_id, "drive_id");
+    const parentItemId = validateOptionalString(args.parent_item_id, "parent_item_id");
+    const customName = validateOptionalString(args.name, "name");
+    const conflictBehavior = validateOptionalEnum(args.conflict_behavior, "conflict_behavior", CONFLICT_BEHAVIORS, "fail");
+    const stat = await fs.stat(localPath);
+    if (!stat.isFile()) {
+        throw new Error(`local_path is not a regular file: ${localPath}`);
+    }
+    checkSizeCap(stat.size);
+    const filename = customName ?? path.basename(localPath);
+    const drivePath = driveId ? `/drives/${encodeURIComponent(driveId)}` : "/me/drive";
+    const parentApi = parentItemId
+        ? `${drivePath}/items/${encodeURIComponent(parentItemId)}`
+        : `${drivePath}/root`;
+    console.error(`[m365-graph-mcp-server] upload_file: ${localPath} (${stat.size} bytes) → ${drivePath}/${parentItemId ?? "<root>"}/${filename}`);
+    let uploadedItem;
+    let uploadPath;
+    if (stat.size <= SMALL_FILE_CAP) {
+        // Small file: single PUT to /items/{parent}:/{name}:/content
+        const content = await fs.readFile(localPath);
+        uploadedItem = (await graph
+            .api(`${parentApi}:/${encodeURIComponent(filename)}:/content`)
+            .query({ "@microsoft.graph.conflictBehavior": conflictBehavior })
+            .put(content));
+        uploadPath = "single_put";
+    }
+    else {
+        // Large file: resumable upload session, 10 MB chunks.
+        const stream = createReadStream(localPath);
+        const fileObject = new StreamUpload(stream, filename, stat.size);
+        // Graph upload-session URL pattern:
+        //   /me/drive/root:/<name>:/createUploadSession                  (root)
+        //   /me/drive/items/<parent-id>:/<name>:/createUploadSession     (sub-folder)
+        //   /drives/<drive-id>/...                                       (non-default drive)
+        const sessionUrl = parentItemId
+            ? `${parentApi}:/${encodeURIComponent(filename)}:/createUploadSession`
+            : `${parentApi}:/${encodeURIComponent(filename)}:/createUploadSession`;
+        const taskOptions = {
+            rangeSize: LARGE_FILE_RANGE,
+        };
+        const uploadSession = await OneDriveLargeFileUploadTask.createUploadSession(graph, sessionUrl, {
+            fileName: filename,
+            conflictBehavior,
+        });
+        const uploadTask = new OneDriveLargeFileUploadTask(graph, fileObject, uploadSession, taskOptions);
+        const taskResult = await uploadTask.upload();
+        uploadedItem = (taskResult.responseBody ?? {});
+        uploadPath = "resumable_session";
+    }
+    const result = {
+        drive_id: driveId ?? null,
+        parent_item_id: parentItemId ?? null,
+        uploaded: {
+            ...summarizeUploadedItem(uploadedItem),
+            upload_path: uploadPath,
+        },
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+};
+export const uploadFileTool = { definition, handler };
+//# sourceMappingURL=upload_file.js.map

package/dist/tools/upload_file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_file.js","sourceRoot":"","sources":["../../src/tools/upload_file.ts"],"names":[],"mappings":"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"}

package/dist/types/tool.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared types for MCP tool definitions in this server.
+ *
+ * Each tool exports a `definition` (the static metadata returned by
+ * tools/list) and a `handler` (the function invoked by tools/call).
+ * The dispatcher in src/index.ts switches on the tool name to call
+ * the right handler.
+ */
+import type { Client } from "@microsoft/microsoft-graph-client";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/**
+ * Return shape for a tool handler. We use the SDK's `CallToolResult`
+ * directly so the dispatcher in `src/index.ts` can return handler
+ * results to `setRequestHandler(CallToolRequestSchema, …)` without a
+ * type assertion.
+ */
+export type ToolResponse = CallToolResult;
+export type ToolHandler = (graph: Client, args: Record<string, unknown>) => Promise<ToolResponse>;
+export interface Tool {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/types/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,YAAY,CAAC,CAAC;AAE3B,MAAM,WAAW,IAAI;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,EAAE,WAAW,CAAC;CACtB"}

package/dist/types/tool.js

@@ -0,0 +1,10 @@
+/**
+ * Shared types for MCP tool definitions in this server.
+ *
+ * Each tool exports a `definition` (the static metadata returned by
+ * tools/list) and a `handler` (the function invoked by tools/call).
+ * The dispatcher in src/index.ts switches on the tool name to call
+ * the right handler.
+ */
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/types/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/types/validators.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Input validators for MCP tool handlers.
+ *
+ * Tool handlers receive `Record<string, unknown>` from the MCP SDK and
+ * must validate each field before passing it to Graph. These helpers
+ * centralize the validation logic + give consistent error messages
+ * the agent can act on.
+ *
+ * Naming convention: every exported helper starts with `validate*`,
+ * which the CI dead-code grep enforces is imported elsewhere in src/.
+ * Defense-in-depth code that's never wired into a real handler is a
+ * security smell (handbook anti-pattern S1).
+ */
+export declare function validateRequiredString(value: unknown, fieldName: string): string;
+export declare function validateOptionalString(value: unknown, fieldName: string): string | undefined;
+export declare function validateOptionalInteger(value: unknown, fieldName: string, options: {
+    min: number;
+    max: number;
+    default: number;
+}): number;
+export declare function validateOptionalEnum<T extends string>(value: unknown, fieldName: string, allowed: ReadonlyArray<T>, defaultValue: T): T;
+/**
+ * Lightweight ISO 8601 date/datetime check. Accepts:
+ *   - YYYY-MM-DD
+ *   - YYYY-MM-DDTHH:MM
+ *   - YYYY-MM-DDTHH:MM:SS
+ *   - YYYY-MM-DDTHH:MM:SS.sss
+ * with optional Z or ±HH:MM timezone offset.
+ *
+ * Microsoft Graph does the strict parsing; we just guard against
+ * obviously-wrong inputs so the agent gets a near-the-input error
+ * rather than a cryptic Graph 400.
+ */
+export declare function validateRequiredISODate(value: unknown, fieldName: string): string;
+/**
+ * Strip path-traversal-dangerous characters from a filename. Used
+ * before constructing a local FS path that includes a server-supplied
+ * filename (e.g. download_file caches the Graph item.name on disk).
+ *
+ * Defense-in-depth: combined with prefix check on path.resolve(), even
+ * a malicious filename ('../../etc/passwd') cannot escape the sandbox.
+ */
+export declare function sanitizeFilename(name: string): string;
+//# sourceMappingURL=validators.d.ts.map

package/dist/types/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/types/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrD,MAAM,CAaR;AAID,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EACnD,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,YAAY,EAAE,CAAC,GACd,CAAC,CAQH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQjF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD"}

package/dist/types/validators.js

@@ -0,0 +1,78 @@
+/**
+ * Input validators for MCP tool handlers.
+ *
+ * Tool handlers receive `Record<string, unknown>` from the MCP SDK and
+ * must validate each field before passing it to Graph. These helpers
+ * centralize the validation logic + give consistent error messages
+ * the agent can act on.
+ *
+ * Naming convention: every exported helper starts with `validate*`,
+ * which the CI dead-code grep enforces is imported elsewhere in src/.
+ * Defense-in-depth code that's never wired into a real handler is a
+ * security smell (handbook anti-pattern S1).
+ */
+export function validateRequiredString(value, fieldName) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`'${fieldName}' must be a non-empty string`);
+    }
+    return value;
+}
+export function validateOptionalString(value, fieldName) {
+    if (value === undefined || value === null)
+        return undefined;
+    return validateRequiredString(value, fieldName);
+}
+export function validateOptionalInteger(value, fieldName, options) {
+    if (value === undefined || value === null)
+        return options.default;
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < options.min ||
+        value > options.max) {
+        throw new Error(`'${fieldName}' must be an integer between ${options.min} and ${options.max}`);
+    }
+    return value;
+}
+const ISO_DATE_LOOKS_LIKE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+export function validateOptionalEnum(value, fieldName, allowed, defaultValue) {
+    if (value === undefined || value === null)
+        return defaultValue;
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        throw new Error(`'${fieldName}' must be one of ${JSON.stringify(allowed)}; got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/**
+ * Lightweight ISO 8601 date/datetime check. Accepts:
+ *   - YYYY-MM-DD
+ *   - YYYY-MM-DDTHH:MM
+ *   - YYYY-MM-DDTHH:MM:SS
+ *   - YYYY-MM-DDTHH:MM:SS.sss
+ * with optional Z or ±HH:MM timezone offset.
+ *
+ * Microsoft Graph does the strict parsing; we just guard against
+ * obviously-wrong inputs so the agent gets a near-the-input error
+ * rather than a cryptic Graph 400.
+ */
+export function validateRequiredISODate(value, fieldName) {
+    const s = validateRequiredString(value, fieldName);
+    if (!ISO_DATE_LOOKS_LIKE.test(s)) {
+        throw new Error(`'${fieldName}' must be an ISO 8601 date or datetime (e.g. '2026-05-04' or '2026-05-04T10:00:00Z'); got ${JSON.stringify(s)}`);
+    }
+    return s;
+}
+/**
+ * Strip path-traversal-dangerous characters from a filename. Used
+ * before constructing a local FS path that includes a server-supplied
+ * filename (e.g. download_file caches the Graph item.name on disk).
+ *
+ * Defense-in-depth: combined with prefix check on path.resolve(), even
+ * a malicious filename ('../../etc/passwd') cannot escape the sandbox.
+ */
+export function sanitizeFilename(name) {
+    return name
+        .replace(/[/\\\0]/g, "_")
+        .replace(/^\.+/, "_") // no leading dots
+        .slice(0, 200);
+}
+//# sourceMappingURL=validators.js.map

package/dist/types/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/types/validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,SAAiB;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,IAAI,SAAS,8BAA8B,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,KAAc,EACd,SAAiB;IAEjB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5D,OAAO,sBAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,KAAc,EACd,SAAiB,EACjB,OAAsD;IAEtD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAClE,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QACxB,KAAK,GAAG,OAAO,CAAC,GAAG;QACnB,KAAK,GAAG,OAAO,CAAC,GAAG,EACnB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,IAAI,SAAS,gCAAgC,OAAO,CAAC,GAAG,QAAQ,OAAO,CAAC,GAAG,EAAE,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,mBAAmB,GAAG,0EAA0E,CAAC;AAEvG,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,SAAiB,EACjB,OAAyB,EACzB,YAAe;IAEf,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAE,OAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CACb,IAAI,SAAS,oBAAoB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,KAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc,EAAE,SAAiB;IACvE,MAAM,CAAC,GAAG,sBAAsB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACnD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,IAAI,SAAS,6FAA6F,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAC9H,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI;SACR,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,kBAAkB;SACvC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACnB,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@juvantlabs/m365-graph-mcp-server",
+  "version": "0.1.0",
+  "description": "Microsoft Graph MCP server — OneDrive, SharePoint, and Calendar read+write for Juvant OS agents.",
+  "license": "MIT",
+  "author": "Juvant Srls",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "m365-graph-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc --pretty false",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test:unit && npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx --env-file=.env.local src/index.ts",
+    "setup": "tsx --env-file=.env.local src/index.ts setup",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit --passWithNoTests",
+    "test:integration": "vitest run tests/integration --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src tests --no-error-on-unmatched-pattern",
+    "typecheck": "tsc --noEmit",
+    "audit": "npm audit --audit-level=moderate"
+  },
+  "dependencies": {
+    "@azure/msal-node": "^5.0.0",
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@napi-rs/keyring": "^1.3.0",
+    "isomorphic-fetch": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/isomorphic-fetch": "^0.0.39",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juvantlabs/m365-graph-mcp-server.git"
+  },
+  "homepage": "https://github.com/juvantlabs/m365-graph-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/juvantlabs/m365-graph-mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "m365-graph",
+    "juvant-os"
+  ]
+}