@habibakhaledm/sharepoint-document-upload-mcp 1.1.3

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@habibakhaledm/sharepoint-document-upload-mcp",
+  "version": "1.1.3",
+  "description": "A MCP server for uploading document to Sharepoint",
+  "main": "src/server.ts",
+  "bin": {
+    "sharepoint-document-upload-mcp": "dist/server.js"
+  },
+  "files": [
+    "bin/**/*.mjs",
+    "src/**/*.ts",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsc",
+    "start": "tsx src/server.ts",
+    "dev": "tsx src/server.ts",
+    "test:mcp": "tsx scripts/run-mcp-upload-test.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HabibaKhaledMohammed/Sharepoint-Document-Upload-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "sharepoint",
+    "microsoft-graph",
+    "upload",
+    "azure"
+  ],
+  "author": "Habiba Khaled Mohammed <habibakhaled606@gmail.com>",
+  "license": "ISC",
+  "type": "module",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.13.1",
+    "@azure/identity-cache-persistence": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.3.1",
+    "tsx": "^4.19.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@types/node": "^22.19.17",
+    "babel-loader": "^10.1.1",
+    "typescript": "^5.7.2",
+    "webpack": "^5.105.4",
+    "webpack-cli": "^7.0.2"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,160 @@
+/** Central configuration literals (no secrets). */
+
+/* Microsoft Graph */
+export const GRAPH_V1_BASE_URL = "https://graph.microsoft.com/v1.0" as const;
+export const GRAPH_BETA_BASE_URL = "https://graph.microsoft.com/beta" as const;
+export const MICROSOFT_AUTH_MODE="interactive" as const;
+export const MICROSOFT_REDIRECT_URI="http://localhost" as const;
+/** Delegated scopes requested for interactive SharePoint upload. */
+export const GRAPH_DELEGATED_SCOPES = [
+  "https://graph.microsoft.com/Sites.Read.All",
+  "https://graph.microsoft.com/Files.ReadWrite.All",
+] as const;
+
+/* Microsoft Entra (interactive public client) */
+export const ENTRA_DEFAULT_REDIRECT_URI =
+  "https://login.microsoftonline.com/common/oauth2/nativeclient" as const;
+
+/** Used when MICROSOFT_TENANT_ID is omitted. */
+export const ENTRA_TENANT_FALLBACK_ORGANIZATIONS = "organizations" as const;
+
+/**
+ * MSAL disk cache folder name under the OS store (e.g. Windows:
+ * %LocalAppData%\\.IdentityService\\<name>). Override with MICROSOFT_TOKEN_CACHE_NAME.
+ * Set MICROSOFT_DISABLE_TOKEN_CACHE=true to skip persistence (browser every run).
+ * If cache init fails without OS encryption, set MICROSOFT_TOKEN_CACHE_UNSAFE_UNENCRYPTED=true.
+ */
+export const MICROSOFT_TOKEN_CACHE_DEFAULT_NAME = "document-upload-mcp-graph" as const;
+
+/**
+ * Account binding file for silent auth (Azure Identity needs this in addition to MSAL token cache).
+ * Default directory: ~/.document-upload-mcp (override MICROSOFT_AUTH_RECORD_DIR).
+ * Delete `auth-record-*.json` there to force sign-in again.
+ */
+export const MICROSOFT_AUTH_RECORD_BASE_DIR = ".document-upload-mcp" as const;
+
+/* SharePoint */
+export const SHAREPOINT_DEFAULT_DOCUMENT_LIBRARY_NAME = "Documents" as const;
+
+/* HTTP (Graph requests) */
+export const HTTP_CONTENT_TYPE_JSON = "application/json" as const;
+export const HTTP_CONTENT_TYPE_OCTET_STREAM = "application/octet-stream" as const;
+
+/* MCP server metadata */
+export const MCP_SERVER_NAME = "sharepoint-document-upload-mcp" as const;
+export const MCP_SERVER_VERSION = "1.0.0" as const;
+export const MCP_SERVER_DESCRIPTION = "A MCP server for uploading document" as const;
+
+/* Local document handling */
+export const ALLOWED_UPLOAD_EXTENSIONS = [
+  ".txt",
+  ".md",
+  ".pdf",
+  ".docx",
+] as const;
+
+export const LOCAL_UPLOAD_DIR = "uploads" as const;
+
+/** Prefix length from SHA-256 hex used in SharePoint upload filenames. */
+export const SHAREPOINT_FILENAME_HASH_PREFIX_LENGTH = 12;
+
+/** Used with `crypto.createHash` for document deduplication and filenames. */
+export const DOCUMENT_HASH_ALGORITHM = "sha256" as const;
+
+/* MCP tools — names, titles, descriptions, responses */
+export const TOOL_NAME_HELLO_WORLD = "hello_world" as const;
+export const TOOL_NAME_UPLOAD_DOCUMENT = "upload_document" as const;
+
+export const TOOL_HELLO_WORLD_TITLE = "Hello World" as const;
+export const TOOL_HELLO_WORLD_DESCRIPTION =
+  "This tool will return Hello World" as const;
+export const TOOL_HELLO_WORLD_RESPONSE_TEXT = "Hello World" as const;
+
+export const TOOL_UPLOAD_DOCUMENT_TITLE = "Upload a document" as const;
+export const TOOL_UPLOAD_DOCUMENT_DESCRIPTION =
+  "Upload a document locally and to SharePoint when configured. Uses interactive Microsoft sign-in with Graph scopes Sites.Read.All and Files.ReadWrite.All only — remove other API permissions on the Entra app for SharePoint-only consent. After the first sign-in, account metadata and tokens are stored on disk (see ~/.document-upload-mcp and OS .IdentityService cache) so later runs usually skip the browser. Set MICROSOFT_DISABLE_TOKEN_CACHE=true only to disable the MSAL file cache." as const;
+
+/** Zod field descriptions for `upload_document` input schema */
+export const SCHEMA_DESC_DOCUMENT_FILENAME =
+  "Original filename including extension (e.g. report.pdf)" as const;
+export const SCHEMA_DESC_DOCUMENT_CONTENT =
+  "File body as UTF-8 text or base64-encoded bytes" as const;
+export const SCHEMA_DESC_MICROSOFT_TENANT_ID =
+  "Entra tenant ID (optional; env MICROSOFT_TENANT_ID; omit for organizations / multi-tenant)" as const;
+export const SCHEMA_DESC_MICROSOFT_CLIENT_ID =
+  "App registration client ID (required for interactive browser sign-in; env MICROSOFT_CLIENT_ID)" as const;
+export const SCHEMA_DESC_SHAREPOINT_SITE_HOST =
+  "SharePoint hostname, e.g. contoso.sharepoint.com (or set SHAREPOINT_SITE_HOST env)" as const;
+export const SCHEMA_DESC_SHAREPOINT_SITE_PATH =
+  "Server-relative site path (e.g. /sites/Team). Use empty string for the root site" as const;
+export const SCHEMA_DESC_SHAREPOINT_UPLOAD_BASE_PATH =
+  "Folder under the document library (e.g. Incoming/2026). Omit or empty for library root" as const;
+
+/* Server messages */
+export const ERR_UNSUPPORTED_FILE_TYPE = "Unsupported file type" as const;
+export const MSG_UPLOAD_SUCCESS_TEMPLATE = (sharePointNote: string) =>
+  `Upload successful.${sharePointNote}`;
+/** Appended when Graph returns a browser URL for the uploaded item. */
+export const MSG_SHAREPOINT_DOC_URL_LINE = (url: string) =>
+  `\n\nSharePoint document URL:\n${url}` as const;
+/** Opaque Microsoft Graph `driveItem` id (for `/drives/.../items/{id}`). */
+export const MSG_SHAREPOINT_DRIVE_ITEM_ID_LINE = (id: string) =>
+  `\n\nMicrosoft Graph drive item id:\n${id}` as const;
+/** SharePoint list row id (often what people mean by "item id" in libraries). */
+export const MSG_SHAREPOINT_LIST_ITEM_ID_LINE = (id: string) =>
+  `\n\nSharePoint list item id:\n${id}` as const;
+export const MSG_SHAREPOINT_LIST_ITEM_UNIQUE_ID_LINE = (id: string) =>
+  `\n\nSharePoint list item unique id:\n${id}` as const;
+export const SP_RESULT_NOTE_COMPLETED =
+  "\n\nSharePoint upload completed (no document URL or ids in API response)." as const;
+
+/* SharePoint / Graph runtime errors (user-facing) */
+export const ERR_INTERACTIVE_NO_GRAPH_TOKEN =
+  "Interactive sign-in did not return a Microsoft Graph token." as const;
+export const ERR_CONSENT_DECLINED_HINT =
+  " Grant only delegated Sites.Read.All and Files.ReadWrite.All on the app registration, then accept consent." as const;
+export const AADSTS65004_SNIPPET = "AADSTS65004" as const;
+export const CONSENT_DECLINED_SNIPPET = "declined to consent" as const;
+
+export const ERR_SHAREPOINT_NO_DRIVES = "No drives found on SharePoint site" as const;
+
+export const ERR_MICROSOFT_CLIENT_ID_REQUIRED = (redirectUri: string) =>
+  `MICROSOFT_CLIENT_ID is required. Use a public Entra client with redirect "${redirectUri}" and delegated Sites.Read.All + Files.ReadWrite.All.`;
+
+export const ERR_GRAPH_FOLDER_CHECK = (
+  pathSoFar: string,
+  status: number,
+  body: string
+) => `Graph folder check ${pathSoFar}: ${status} ${body}`;
+
+export const ERR_GRAPH_CREATE_FOLDER = (
+  segment: string,
+  parentPath: string,
+  status: number,
+  body: string
+) =>
+  `Create folder "${segment}" under "${parentPath || "root"}": ${status} ${body}`;
+
+export const MICROSOFT_GRAPH_CONFLICT_BEHAVIOR_FAIL = "fail" as const;
+
+/** Set to `1` to log why `*-my.sharepoint.com/shared` URL construction was skipped. */
+export const DEBUG_SHAREPOINT_MY_URL_ENV = "SHAREPOINT_DEBUG_MY_URL" as const;
+
+/* Graph client error prefixes */
+export const ERR_GRAPH_GET = (graphPath: string, status: number, body: string) =>
+  `Graph GET ${graphPath}: ${status} ${body}`;
+export const ERR_GRAPH_PUT = (graphPath: string, status: number, body: string) =>
+  `Graph PUT ${graphPath}: ${status} ${body}`;
+
+/* Integration test script (run-mcp-upload-test) */
+export const MCP_UPLOAD_TEST_CLIENT_NAME = "upload-test" as const;
+export const MCP_UPLOAD_TEST_CLIENT_VERSION = "1.0.0" as const;
+export const MCP_CALL_TIMEOUT_ENV = "MCP_CALL_TIMEOUT_MS" as const;
+export const MCP_CALL_TIMEOUT_DEFAULT_MS = 900_000;
+/** Default fixture under `fixtures/`; override with env MCP_UPLOAD_TEST_FIXTURE. */
+export const FIXTURE_UPLOAD_TEST_FILENAME = "mcp-random-test.md" as const;
+export const MCP_UPLOAD_TEST_FIXTURE_ENV = "MCP_UPLOAD_TEST_FIXTURE" as const;
+
+/** Project-relative paths (repo root). */
+export const PROJECT_REL_TSX_CLI = "node_modules/tsx/dist/cli.mjs" as const;
+export const PROJECT_REL_SERVER_ENTRY = "src/server.ts" as const;

package/src/document-upload.ts

@@ -0,0 +1,97 @@
+import {
+    ALLOWED_UPLOAD_EXTENSIONS,
+    DOCUMENT_HASH_ALGORITHM,
+    ERR_UNSUPPORTED_FILE_TYPE,
+    LOCAL_UPLOAD_DIR,
+    MSG_SHAREPOINT_DOC_URL_LINE,
+    MSG_SHAREPOINT_DRIVE_ITEM_ID_LINE,
+    MSG_SHAREPOINT_LIST_ITEM_ID_LINE,
+    MSG_SHAREPOINT_LIST_ITEM_UNIQUE_ID_LINE,
+    SHAREPOINT_FILENAME_HASH_PREFIX_LENGTH,
+    SP_RESULT_NOTE_COMPLETED,
+  } from "./constants.js";
+import { uploadBufferToSharePointIfConfigured } from "./sharepoint.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+
+export async function  uploadDocument(
+    document: {
+        filename: string;
+        content: string;
+    },
+    MICROSOFT_TENANT_ID: string,
+    MICROSOFT_CLIENT_ID: string,
+    SHAREPOINT_SITE_HOST: string,
+    SHAREPOINT_SITE_PATH: string,
+    SHAREPOINT_UPLOAD_BASE_PATH: string
+){
+    const { filename, content } = document;
+
+    const ext = path.extname(filename).toLowerCase();
+    if (!(ALLOWED_UPLOAD_EXTENSIONS as readonly string[]).includes(ext)) {
+      throw new Error(ERR_UNSUPPORTED_FILE_TYPE);
+    }
+
+    const uploadDir = path.resolve(LOCAL_UPLOAD_DIR);
+    await fs.mkdir(uploadDir, { recursive: true });
+
+    const filePath = path.join(uploadDir, filename);
+
+    const buffer = isBase64(content)
+      ? Buffer.from(content, "base64")
+      : Buffer.from(content, "utf-8");
+
+    await fs.writeFile(filePath, buffer);
+
+    const hash = crypto.createHash(DOCUMENT_HASH_ALGORITHM).update(buffer).digest("hex");
+
+    const sp = await uploadBufferToSharePointIfConfigured(
+      buffer,
+      `${hash.slice(0, SHAREPOINT_FILENAME_HASH_PREFIX_LENGTH)}_${filename}`,
+      {
+        MICROSOFT_TENANT_ID,
+        MICROSOFT_CLIENT_ID,
+        SHAREPOINT_SITE_HOST,
+        SHAREPOINT_SITE_PATH,
+        SHAREPOINT_UPLOAD_BASE_PATH,
+      }
+    );
+    const spNote = formatSharePointResultNote(sp);
+    return spNote;
+
+}
+function formatSharePointResultNote(
+    sp: Awaited<ReturnType<typeof uploadBufferToSharePointIfConfigured>>
+  ): string {
+    if (sp.skipped) {
+      return "";
+    }
+    const parts: string[] = [];
+    if (sp.webUrl) {
+      parts.push(MSG_SHAREPOINT_DOC_URL_LINE(sp.webUrl));
+    }
+    if (sp.driveItemId) {
+      parts.push(MSG_SHAREPOINT_DRIVE_ITEM_ID_LINE(sp.driveItemId));
+    }
+    const listItemId = sp.sharepointIds?.listItemId;
+    if (listItemId) {
+      parts.push(MSG_SHAREPOINT_LIST_ITEM_ID_LINE(listItemId));
+    }
+    const uniqueId = sp.sharepointIds?.listItemUniqueId;
+    if (uniqueId) {
+      parts.push(MSG_SHAREPOINT_LIST_ITEM_UNIQUE_ID_LINE(uniqueId));
+    }
+    if (parts.length > 0) {
+      return parts.join("");
+    }
+    return SP_RESULT_NOTE_COMPLETED;
+  }
+  
+  function isBase64(str: string): boolean {
+    try {
+      return Buffer.from(str, "base64").toString("base64") === str;
+    } catch {
+      return false;
+    }
+  }

package/src/graph-client.ts

@@ -0,0 +1,85 @@
+/** Minimal Microsoft Graph v1 HTTP helpers (Bearer token). */
+
+import {
+  ERR_GRAPH_GET,
+  ERR_GRAPH_PUT,
+  GRAPH_BETA_BASE_URL,
+  GRAPH_V1_BASE_URL,
+  HTTP_CONTENT_TYPE_OCTET_STREAM,
+} from "./constants.js";
+
+export const GRAPH_V1_ROOT = GRAPH_V1_BASE_URL;
+export const GRAPH_BETA_ROOT = GRAPH_BETA_BASE_URL;
+
+/** Subset of DriveItem fields used after upload / metadata reads. */
+export type GraphDriveItemSummary = {
+  id?: string;
+  webUrl?: string;
+  sharepointIds?: {
+    listId?: string;
+    listItemId?: string;
+    listItemUniqueId?: string;
+    siteId?: string;
+  };
+};
+
+/** Drive item path: encode each path segment (handles `/`, `&`, spaces). */
+export function encodeDriveRelativePath(relativePath: string): string {
+  return relativePath
+    .split("/")
+    .filter(Boolean)
+    .map((s) => encodeURIComponent(s))
+    .join("/");
+}
+
+export async function graphRequest(
+  token: string,
+  graphPath: string,
+  init?: RequestInit
+): Promise<Response> {
+  const headers = new Headers(init?.headers ?? undefined);
+  headers.set("Authorization", `Bearer ${token}`);
+  return fetch(`${GRAPH_V1_ROOT}${graphPath}`, { ...init, headers });
+}
+
+export async function graphGetJson<T>(token: string, graphPath: string): Promise<T> {
+  const res = await graphRequest(token, graphPath);
+  if (!res.ok) {
+    throw new Error(ERR_GRAPH_GET(graphPath, res.status, await res.text()));
+  }
+  return res.json() as Promise<T>;
+}
+
+export async function graphBetaGetJson<T>(token: string, graphPath: string): Promise<T> {
+  const headers = new Headers();
+  headers.set("Authorization", `Bearer ${token}`);
+  const res = await fetch(`${GRAPH_BETA_ROOT}${graphPath}`, { headers });
+  if (!res.ok) {
+    throw new Error(ERR_GRAPH_GET(`[beta]${graphPath}`, res.status, await res.text()));
+  }
+  return res.json() as Promise<T>;
+}
+
+export async function graphPutStream(
+  token: string,
+  graphPath: string,
+  body: Buffer
+): Promise<GraphDriveItemSummary> {
+  const res = await graphRequest(token, graphPath, {
+    method: "PUT",
+    headers: { "Content-Type": HTTP_CONTENT_TYPE_OCTET_STREAM },
+    body: new Uint8Array(body),
+  });
+  if (!res.ok) {
+    throw new Error(ERR_GRAPH_PUT(graphPath, res.status, await res.text()));
+  }
+  const raw = await res.text();
+  if (!raw.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(raw) as GraphDriveItemSummary;
+  } catch {
+    return {};
+  }
+}

package/src/server.ts

@@ -0,0 +1,106 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  MCP_SERVER_DESCRIPTION,
+  MCP_SERVER_NAME,
+  MCP_SERVER_VERSION,
+  MSG_UPLOAD_SUCCESS_TEMPLATE,
+  SCHEMA_DESC_DOCUMENT_CONTENT,
+  SCHEMA_DESC_DOCUMENT_FILENAME,
+  SCHEMA_DESC_MICROSOFT_CLIENT_ID,
+  SCHEMA_DESC_MICROSOFT_TENANT_ID,
+  SCHEMA_DESC_SHAREPOINT_SITE_HOST,
+  SCHEMA_DESC_SHAREPOINT_SITE_PATH,
+  SCHEMA_DESC_SHAREPOINT_UPLOAD_BASE_PATH,
+  TOOL_HELLO_WORLD_RESPONSE_TEXT,
+  TOOL_HELLO_WORLD_TITLE,
+  TOOL_NAME_HELLO_WORLD,
+  TOOL_NAME_UPLOAD_DOCUMENT,
+  TOOL_UPLOAD_DOCUMENT_DESCRIPTION,
+  TOOL_UPLOAD_DOCUMENT_TITLE,
+  TOOL_HELLO_WORLD_DESCRIPTION
+} from "./constants.js";
+import { uploadDocument } from "./document-upload.js";
+
+const server = new McpServer({
+  name: MCP_SERVER_NAME,
+  version: MCP_SERVER_VERSION,
+  description: MCP_SERVER_DESCRIPTION,
+});
+server.registerTool(
+  TOOL_NAME_HELLO_WORLD,
+  {
+    title: TOOL_HELLO_WORLD_TITLE,
+    description: TOOL_HELLO_WORLD_DESCRIPTION,
+    inputSchema: {}
+  },
+  async () => {
+    return {  content: [
+        {
+          type: "text",
+          text: TOOL_HELLO_WORLD_RESPONSE_TEXT,
+        },
+      ],
+    };
+  }
+);
+
+server.registerTool(
+  TOOL_NAME_UPLOAD_DOCUMENT,
+  {
+    title: TOOL_UPLOAD_DOCUMENT_TITLE,
+    description: TOOL_UPLOAD_DOCUMENT_DESCRIPTION,
+    inputSchema: z.object({
+      document: z.object({
+        filename: z.string().describe(SCHEMA_DESC_DOCUMENT_FILENAME),
+        content: z.string().describe(SCHEMA_DESC_DOCUMENT_CONTENT),
+      }),
+      MICROSOFT_TENANT_ID: z
+        .string()
+        .describe(SCHEMA_DESC_MICROSOFT_TENANT_ID),
+      MICROSOFT_CLIENT_ID: z
+        .string()
+        .describe(SCHEMA_DESC_MICROSOFT_CLIENT_ID),
+      SHAREPOINT_SITE_HOST: z
+        .string()
+        .describe(SCHEMA_DESC_SHAREPOINT_SITE_HOST),
+      SHAREPOINT_SITE_PATH: z
+        .string()
+        .describe(SCHEMA_DESC_SHAREPOINT_SITE_PATH),
+      SHAREPOINT_UPLOAD_BASE_PATH: z
+        .string()
+        .describe(SCHEMA_DESC_SHAREPOINT_UPLOAD_BASE_PATH),
+    }),
+  },
+  async ({
+    document,
+    MICROSOFT_TENANT_ID,
+    MICROSOFT_CLIENT_ID,
+    SHAREPOINT_SITE_HOST,
+    SHAREPOINT_SITE_PATH,
+    SHAREPOINT_UPLOAD_BASE_PATH,
+  }) => {
+    const spNote = await uploadDocument( document,
+      MICROSOFT_TENANT_ID,
+      MICROSOFT_CLIENT_ID,
+      SHAREPOINT_SITE_HOST,
+      SHAREPOINT_SITE_PATH,
+      SHAREPOINT_UPLOAD_BASE_PATH,
+    );
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: MSG_UPLOAD_SUCCESS_TEMPLATE(spNote),
+        },
+      ],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/sharepoint.ts

@@ -0,0 +1,874 @@
+/**
+ * SharePoint upload via Microsoft Graph + interactive browser sign-in.
+ * See `constants.ts` for Graph scopes, redirect URI, and defaults.
+ */
+
+import {
+  InteractiveBrowserCredential,
+  deserializeAuthenticationRecord,
+  serializeAuthenticationRecord,
+  useIdentityPlugin,
+  type AuthenticationRecord,
+} from "@azure/identity";
+import { cachePersistencePlugin } from "@azure/identity-cache-persistence";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  AADSTS65004_SNIPPET,
+  CONSENT_DECLINED_SNIPPET,
+  ENTRA_DEFAULT_REDIRECT_URI,
+  ENTRA_TENANT_FALLBACK_ORGANIZATIONS,
+  ERR_CONSENT_DECLINED_HINT,
+  ERR_GRAPH_CREATE_FOLDER,
+  ERR_GRAPH_FOLDER_CHECK,
+  ERR_INTERACTIVE_NO_GRAPH_TOKEN,
+  ERR_MICROSOFT_CLIENT_ID_REQUIRED,
+  ERR_SHAREPOINT_NO_DRIVES,
+  DOCUMENT_HASH_ALGORITHM,
+  GRAPH_DELEGATED_SCOPES,
+  HTTP_CONTENT_TYPE_JSON,
+  MCP_SERVER_NAME,
+  MICROSOFT_AUTH_RECORD_BASE_DIR,
+  DEBUG_SHAREPOINT_MY_URL_ENV,
+  MICROSOFT_GRAPH_CONFLICT_BEHAVIOR_FAIL,
+  MICROSOFT_TOKEN_CACHE_DEFAULT_NAME,
+  SHAREPOINT_DEFAULT_DOCUMENT_LIBRARY_NAME,
+  MICROSOFT_REDIRECT_URI,
+} from "./constants.js";
+import {
+  encodeDriveRelativePath,
+  type GraphDriveItemSummary,
+  graphBetaGetJson,
+  graphGetJson,
+  graphPutStream,
+  graphRequest,
+} from "./graph-client.js";
+
+/** Re-export for callers that imported redirect from this module. */
+export const DEFAULT_REDIRECT_URI = ENTRA_DEFAULT_REDIRECT_URI;
+
+let msalPersistencePluginAttempted = false;
+let msalPersistencePluginRegistered = false;
+
+function ensureMsalPersistencePlugin(): boolean {
+  if (msalPersistencePluginRegistered) {
+    return true;
+  }
+  if (msalPersistencePluginAttempted) {
+    return false;
+  }
+  msalPersistencePluginAttempted = true;
+
+  const disabled = process.env.MICROSOFT_DISABLE_TOKEN_CACHE;
+  if (disabled === "1" || disabled === "true") {
+    return false;
+  }
+
+  try {
+    useIdentityPlugin(cachePersistencePlugin);
+    msalPersistencePluginRegistered = true;
+    return true;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(
+      `[${MCP_SERVER_NAME}] MSAL token cache plugin failed (${msg}). Browser sign-in may be required every run.`
+    );
+    return false;
+  }
+}
+
+function resolveTokenCachePersistenceOptions():
+  | { enabled: true; name: string; unsafeAllowUnencryptedStorage?: boolean }
+  | undefined {
+  if (!ensureMsalPersistencePlugin()) {
+    return undefined;
+  }
+  const name =
+    process.env.MICROSOFT_TOKEN_CACHE_NAME?.trim() ||
+    MICROSOFT_TOKEN_CACHE_DEFAULT_NAME;
+  const unsafe =
+    process.env.MICROSOFT_TOKEN_CACHE_UNSAFE_UNENCRYPTED === "1" ||
+    process.env.MICROSOFT_TOKEN_CACHE_UNSAFE_UNENCRYPTED === "true";
+  return {
+    enabled: true,
+    name,
+    ...(unsafe ? { unsafeAllowUnencryptedStorage: true as const } : {}),
+  };
+}
+
+export type SharePointUploadOverrides = {
+  MICROSOFT_TENANT_ID?: string;
+  MICROSOFT_CLIENT_ID?: string;
+  SHAREPOINT_SITE_HOST?: string;
+  SHAREPOINT_SITE_PATH?: string;
+  SHAREPOINT_UPLOAD_BASE_PATH?: string;
+};
+
+type ResolvedSiteConfig = {
+  tenantId?: string;
+  clientId?: string;
+  redirectUri: string;
+  siteHost: string;
+  sitePath: string;
+  folderPath: string;
+  driveName: string;
+};
+
+function pick(
+  override: string | undefined,
+  ...envKeys: string[]
+): string | undefined {
+  if (override !== undefined) {
+    return override;
+  }
+  for (const key of envKeys) {
+    const v = process.env[key];
+    if (v !== undefined && v !== "") {
+      return v;
+    }
+  }
+  return undefined;
+}
+
+function normalizeSitePath(path: string): string {
+  const p = path.trim();
+  return p.startsWith(":") ? p.slice(1) : p;
+}
+
+function resolveSiteConfig(
+  overrides?: SharePointUploadOverrides
+): ResolvedSiteConfig | null {
+  const siteHost = pick(overrides?.SHAREPOINT_SITE_HOST, "SHAREPOINT_SITE_HOST");
+  if (!siteHost) {
+    return null;
+  }
+
+  const rawPath =
+    pick(overrides?.SHAREPOINT_SITE_PATH, "SHAREPOINT_SITE_PATH") ?? "";
+
+  return {
+    tenantId: pick(overrides?.MICROSOFT_TENANT_ID, "MICROSOFT_TENANT_ID"),
+    clientId: pick(overrides?.MICROSOFT_CLIENT_ID, "MICROSOFT_CLIENT_ID"),
+    redirectUri:
+      pick(undefined, "MICROSOFT_REDIRECT_URI") ?? MICROSOFT_REDIRECT_URI,
+    siteHost,
+    sitePath: normalizeSitePath(rawPath),
+    folderPath:
+      pick(
+        overrides?.SHAREPOINT_UPLOAD_BASE_PATH,
+        "SHAREPOINT_UPLOAD_BASE_PATH",
+        "SHAREPOINT_FOLDER_PATH"
+      ) ?? "",
+    driveName:
+      pick(undefined, "SHAREPOINT_DRIVE_NAME") ??
+      SHAREPOINT_DEFAULT_DOCUMENT_LIBRARY_NAME,
+  };
+}
+
+const GRAPH_SITE_WEB_GUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * `GET /sites/{id}` returns composite ids `hostname,{siteCollectionId},{webId}`.
+ * List subpaths like `/lists/{listId}/views` return 400 with the composite form; use the web GUID.
+ */
+function siteIdForListScopedRequests(siteId: string): string {
+  const segments = siteId.split(",").map((s) => s.trim());
+  if (segments.length === 3) {
+    const webId = segments[2];
+    if (webId && GRAPH_SITE_WEB_GUID_RE.test(webId)) {
+      return webId;
+    }
+  }
+  const trimmed = siteId.trim();
+  if (GRAPH_SITE_WEB_GUID_RE.test(trimmed)) {
+    return trimmed;
+  }
+  return siteId;
+}
+
+function credentialBindingKey(
+  tenantId: string,
+  clientId: string,
+  redirectUri: string
+): string {
+  return `${tenantId}|${clientId}|${redirectUri}`;
+}
+
+function authenticationRecordFilePath(bindingKey: string): string {
+  const dir =
+    process.env.MICROSOFT_AUTH_RECORD_DIR?.trim() ||
+    path.join(os.homedir(), MICROSOFT_AUTH_RECORD_BASE_DIR);
+  const hash = crypto
+    .createHash(DOCUMENT_HASH_ALGORITHM)
+    .update(bindingKey)
+    .digest("hex")
+    .slice(0, 24);
+  return path.join(dir, `auth-record-${hash}.json`);
+}
+
+async function loadSavedAuthenticationRecord(
+  bindingKey: string
+): Promise<AuthenticationRecord | undefined> {
+  try {
+    const raw = await fs.readFile(authenticationRecordFilePath(bindingKey), "utf-8");
+    return deserializeAuthenticationRecord(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+async function saveAuthenticationRecord(
+  bindingKey: string,
+  record: AuthenticationRecord
+): Promise<void> {
+  const filePath = authenticationRecordFilePath(bindingKey);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, serializeAuthenticationRecord(record), "utf-8");
+}
+
+function rethrowWithConsentMessageIfNeeded(e: unknown): never {
+  const msg = e instanceof Error ? e.message : String(e);
+  if (
+    msg.includes(AADSTS65004_SNIPPET) ||
+    msg.includes(CONSENT_DECLINED_SNIPPET)
+  ) {
+    throw new Error(`${msg}${ERR_CONSENT_DECLINED_HINT}`);
+  }
+  throw e;
+}
+
+async function acquireGraphToken(
+  tenantId: string | undefined,
+  clientId: string,
+  redirectUri: string
+): Promise<string> {
+  const tenant = tenantId?.trim() || ENTRA_TENANT_FALLBACK_ORGANIZATIONS;
+  const bindingKey = credentialBindingKey(tenant, clientId, redirectUri);
+  let record = await loadSavedAuthenticationRecord(bindingKey);
+  const persistence = resolveTokenCachePersistenceOptions();
+
+  const credential = new InteractiveBrowserCredential({
+    tenantId: tenant,
+    clientId,
+    redirectUri,
+    ...(record ? { authenticationRecord: record } : {}),
+    ...(persistence ? { tokenCachePersistenceOptions: persistence } : {}),
+  });
+
+  if (!record) {
+    try {
+      const interactiveRecord = await credential.authenticate([
+        ...GRAPH_DELEGATED_SCOPES,
+      ]);
+      if (!interactiveRecord) {
+        throw new Error(ERR_INTERACTIVE_NO_GRAPH_TOKEN);
+      }
+      await saveAuthenticationRecord(bindingKey, interactiveRecord);
+    } catch (e) {
+      rethrowWithConsentMessageIfNeeded(e);
+    }
+  }
+
+  try {
+    const result = await credential.getToken([...GRAPH_DELEGATED_SCOPES]);
+    if (!result?.token) {
+      throw new Error(ERR_INTERACTIVE_NO_GRAPH_TOKEN);
+    }
+    return result.token;
+  } catch (e) {
+    rethrowWithConsentMessageIfNeeded(e);
+  }
+}
+
+function sitePathToGraphKey(host: string, sitePath: string): string {
+  const seg = sitePath.trim();
+  if (seg === "" || seg === "/") {
+    return encodeURIComponent(`${host}:/`);
+  }
+  const normalized = seg.startsWith("/") ? seg : `/${seg}`;
+  return encodeURIComponent(`${host}:${normalized}`);
+}
+
+async function resolveSiteAndDriveIds(
+  token: string,
+  host: string,
+  sitePath: string,
+  driveName: string
+): Promise<{ siteId: string; driveId: string }> {
+  const siteId = (
+    await graphGetJson<{ id: string }>(
+      token,
+      `/sites/${sitePathToGraphKey(host, sitePath)}`
+    )
+  ).id;
+
+  const drives = await graphGetJson<{ value: { id: string; name: string }[] }>(
+    token,
+    `/sites/${encodeURIComponent(siteId)}/drives`
+  );
+  const drive =
+    drives.value.find((d) => d.name === driveName) ?? drives.value[0];
+  if (!drive) {
+    throw new Error(ERR_SHAREPOINT_NO_DRIVES);
+  }
+  return { siteId, driveId: drive.id };
+}
+
+function mergeDriveItemMeta(
+  a: GraphDriveItemSummary,
+  b: GraphDriveItemSummary
+): GraphDriveItemSummary {
+  const sharepointIds =
+    a.sharepointIds || b.sharepointIds
+      ? { ...a.sharepointIds, ...b.sharepointIds }
+      : undefined;
+  return {
+    id: b.id ?? a.id,
+    webUrl: b.webUrl ?? a.webUrl,
+    sharepointIds,
+  };
+}
+
+async function getDriveItemBySiteDrivePath(
+  token: string,
+  siteId: string,
+  driveId: string,
+  encodedRelativePath: string
+): Promise<GraphDriveItemSummary> {
+  const select = "id,webUrl,sharepointIds";
+  const metaPath = `/sites/${encodeURIComponent(siteId)}/drives/${encodeURIComponent(driveId)}/root:/${encodedRelativePath}?$select=${select}`;
+  return graphGetJson<GraphDriveItemSummary>(token, metaPath);
+}
+
+function sharePointHostnameWithoutScheme(siteHost: string): string {
+  return siteHost.replace(/^https?:\/\//i, "").replace(/\/.*$/, "");
+}
+
+/** e.g. `integrantincorp` from `integrantincorp.sharepoint.com`. */
+function tenantKeyFromSharePointHost(hostname: string): string | undefined {
+  const lower = hostname.toLowerCase();
+  const suffix = ".sharepoint.com";
+  if (!lower.endsWith(suffix)) {
+    return undefined;
+  }
+  const sub = lower.slice(0, -suffix.length);
+  const first = sub.split(".")[0];
+  return first || undefined;
+}
+
+function serverRelativeItemPathFromGraphWebUrl(itemWebUrl: string): string {
+  const u = new URL(itemWebUrl);
+  const path = u.pathname.replace(/\/+$/, "") || u.pathname;
+  return decodeURIComponent(path);
+}
+
+function parentServerRelativePathFromItem(itemPath: string): string {
+  const i = itemPath.lastIndexOf("/");
+  if (i <= 0) {
+    return itemPath;
+  }
+  return itemPath.slice(0, i);
+}
+
+/** Decode URL until stable so `.../Shared%2520Documents` becomes a single-encoded path for `listurl`. */
+function normalizeUrlForSharedListParam(url: string): string {
+  let s = url.trim();
+  let prev = "";
+  while (s !== prev && /%[0-9a-f]{2}/i.test(s)) {
+    prev = s;
+    try {
+      s = decodeURIComponent(s);
+    } catch {
+      break;
+    }
+  }
+  return s;
+}
+
+function buildMySharedQueryString(params: {
+  listurl: string;
+  viewid?: string;
+  id: string;
+  parent: string;
+  ovuser?: string;
+}): string {
+  const listurl = normalizeUrlForSharedListParam(params.listurl);
+  const parts: string[] = [`listurl=${encodeURIComponent(listurl)}`];
+  if (params.viewid?.trim()) {
+    parts.push(`viewid=${encodeURIComponent(params.viewid.trim())}`);
+  }
+  parts.push(`id=${encodeURIComponent(params.id)}`);
+  parts.push(`parent=${encodeURIComponent(params.parent)}`);
+  if (params.ovuser?.trim()) {
+    parts.push(`ovuser=${encodeURIComponent(params.ovuser.trim())}`);
+  }
+  return parts.join("&");
+}
+
+async function fetchListWebRootUrl(
+  token: string,
+  siteId: string,
+  listId: string
+): Promise<string | undefined> {
+  const sid = siteIdForListScopedRequests(siteId);
+  const list = await graphGetJson<{ webUrl?: string }>(
+    token,
+    `/sites/${encodeURIComponent(sid)}/lists/${encodeURIComponent(
+      listId
+    )}?$select=webUrl`
+  );
+  const u = list.webUrl?.trim();
+  return u || undefined;
+}
+
+function logMySharedUrlDebug(message: string, err?: unknown): void {
+  if (process.env[DEBUG_SHAREPOINT_MY_URL_ENV] !== "1") {
+    return;
+  }
+  const detail = err instanceof Error ? err.message : err;
+  console.error(`[${MCP_SERVER_NAME}] my/shared URL: ${message}`, detail ?? "");
+}
+
+/**
+ * Graph list `id` + library webUrl for the document library drive.
+ * Prefer site-scoped `/sites/.../drives/.../list` (works for SharePoint libraries).
+ */
+async function fetchDriveDocumentLibraryList(
+  token: string,
+  siteId: string,
+  driveId: string
+): Promise<{ id: string; webUrl?: string } | undefined> {
+  const select = "$select=id,webUrl";
+  const attempts: { label: string; path: string }[] = [
+    {
+      label: "site+drive /list",
+      path: `/sites/${encodeURIComponent(siteId)}/drives/${encodeURIComponent(
+        driveId
+      )}/list?${select}`,
+    },
+    {
+      label: "/drives /list",
+      path: `/drives/${encodeURIComponent(driveId)}/list?${select}`,
+    },
+    {
+      label: "/drives $expand=list",
+      path: `/drives/${encodeURIComponent(driveId)}?$expand=list`,
+    },
+  ];
+
+  for (const { label, path } of attempts) {
+    try {
+      if (path.includes("$expand=list")) {
+        const drive = await graphGetJson<{
+          list?: { id: string; webUrl?: string };
+        }>(token, path);
+        if (drive.list?.id) {
+          return { id: drive.list.id, webUrl: drive.list.webUrl };
+        }
+      } else {
+        const list = await graphGetJson<{ id: string; webUrl?: string }>(
+          token,
+          path
+        );
+        if (list?.id) {
+          return { id: list.id, webUrl: list.webUrl };
+        }
+      }
+    } catch (e) {
+      logMySharedUrlDebug(`${label} failed`, e);
+    }
+  }
+  logMySharedUrlDebug("no list id from site/drives list endpoints or expand");
+  return undefined;
+}
+
+type GraphListViewRow = {
+  id: string;
+  name?: string;
+  displayName?: string;
+};
+
+function pickPreferredLibraryViewId(views: GraphListViewRow[]): string | undefined {
+  if (!views.length) {
+    return undefined;
+  }
+  const preferred =
+    views.find((v) => v.name === "All Documents") ??
+    views.find((v) => /all\s*documents/i.test(v.name ?? "")) ??
+    views.find((v) => /all\s*documents/i.test(v.displayName ?? "")) ??
+    views[0];
+  return preferred?.id;
+}
+
+/**
+ * Resolves `viewid` for `*-my.sharepoint.com/shared`. Document libraries often reject
+ * `.../lists/{id}/views` on v1; we try `$expand=views`, then v1 `/views`, then beta `/views`.
+ */
+async function fetchLibraryViewIdForSharedLink(
+  token: string,
+  siteId: string,
+  listId: string
+): Promise<string | undefined> {
+  const sid = siteIdForListScopedRequests(siteId);
+  const listBase = `/sites/${encodeURIComponent(sid)}/lists/${encodeURIComponent(
+    listId
+  )}`;
+
+  try {
+    const expanded = await graphGetJson<{
+      views?: GraphListViewRow[];
+    }>(
+      token,
+      `${listBase}?$expand=views($select=id,name,displayName)&$select=id`
+    );
+    const vid = pickPreferredLibraryViewId(expanded.views ?? []);
+    if (vid) {
+      return vid;
+    }
+  } catch (e) {
+    logMySharedUrlDebug("list $expand=views (v1) failed", e);
+  }
+
+  try {
+    const data = await graphGetJson<{ value: GraphListViewRow[] }>(
+      token,
+      `${listBase}/views`
+    );
+    const vid = pickPreferredLibraryViewId(data.value ?? []);
+    if (vid) {
+      return vid;
+    }
+  } catch (e) {
+    logMySharedUrlDebug("list /views (v1) failed", e);
+  }
+
+  try {
+    const data = await graphBetaGetJson<{ value: GraphListViewRow[] }>(
+      token,
+      `${listBase}/views`
+    );
+    const vid = pickPreferredLibraryViewId(data.value ?? []);
+    if (vid) {
+      return vid;
+    }
+  } catch (e) {
+    logMySharedUrlDebug("list /views (beta) failed", e);
+  }
+
+  return undefined;
+}
+
+/**
+ * Browser often opens library files via
+ * `https://{tenant}-my.sharepoint.com/shared?listurl=&viewid=&id=&parent=` (and optional `ovuser`).
+ * Graph `webUrl` alone points at `*.sharepoint.com/...`, which may not match what users copy from the address bar.
+ * Omits `xsdata` / `sdata` (session tokens); those are not available server-side.
+ */
+async function tryBuildSharePointMySharedDocumentUrl(options: {
+  token: string;
+  siteId: string;
+  driveId: string;
+  /** From driveItem.sharepointIds; used only if `/drives/{id}/list` is unavailable. */
+  listIdFromSharepointIds?: string;
+  itemWebUrl: string;
+  sharePointSiteHost: string;
+  tenantId?: string;
+}): Promise<string | undefined> {
+  const {
+    token,
+    siteId,
+    driveId,
+    listIdFromSharepointIds,
+    itemWebUrl,
+    sharePointSiteHost,
+    tenantId,
+  } = options;
+
+  const host = sharePointHostnameWithoutScheme(sharePointSiteHost);
+  const tenantKey = tenantKeyFromSharePointHost(host);
+  if (!tenantKey) {
+    logMySharedUrlDebug("could not derive tenant prefix", host);
+    return undefined;
+  }
+
+  const libraryList =
+    (await fetchDriveDocumentLibraryList(token, siteId, driveId)) ??
+    (listIdFromSharepointIds
+      ? { id: listIdFromSharepointIds, webUrl: undefined }
+      : undefined);
+  if (!libraryList?.id) {
+    logMySharedUrlDebug("no library list id (drive list + sharepointIds exhausted)");
+    return undefined;
+  }
+  const listId = libraryList.id;
+
+  let listWebUrl: string | undefined = libraryList.webUrl?.trim();
+  if (!listWebUrl) {
+    try {
+      listWebUrl = await fetchListWebRootUrl(token, siteId, listId);
+    } catch {
+      return undefined;
+    }
+  }
+  if (!listWebUrl) {
+    logMySharedUrlDebug("no list webUrl", { listId });
+    return undefined;
+  }
+
+  const viewId = await fetchLibraryViewIdForSharedLink(token, siteId, listId);
+  if (!viewId) {
+    logMySharedUrlDebug(
+      "no view id discovered; continuing without viewid query param",
+      { listId }
+    );
+  }
+
+  let itemPath: string;
+  try {
+    itemPath = serverRelativeItemPathFromGraphWebUrl(itemWebUrl);
+    if (!itemPath.startsWith("/")) {
+      logMySharedUrlDebug("item path not server-relative", itemPath);
+      return undefined;
+    }
+  } catch (e) {
+    logMySharedUrlDebug("parse item webUrl failed", e);
+    return undefined;
+  }
+
+  const parentPath = parentServerRelativePathFromItem(itemPath);
+  const base = `https://${tenantKey}-my.sharepoint.com/shared`;
+
+  let ovuser: string | undefined;
+  const tid = tenantId?.trim();
+  if (tid) {
+    try {
+      const me = await graphGetJson<{ userPrincipalName?: string }>(
+        token,
+        "/me?$select=userPrincipalName"
+      );
+      const upn = me.userPrincipalName?.trim();
+      if (upn) {
+        ovuser = `${tid},${upn}`;
+      }
+    } catch {
+      /* ovuser is optional */
+    }
+  }
+
+  const q = buildMySharedQueryString({
+    listurl: listWebUrl,
+    viewid: viewId,
+    id: itemPath,
+    parent: parentPath,
+    ovuser,
+  });
+  return `${base}?${q}`;
+}
+
+/**
+ * Creates an org-scoped **view** link via Graph; `link.webUrl` generally opens in the
+ * browser even when the raw driveItem `webUrl` does not.
+ */
+async function tryCreateOrganizationViewLink(
+  token: string,
+  siteId: string,
+  driveId: string,
+  itemId: string
+): Promise<string | undefined> {
+  const path = `/sites/${encodeURIComponent(siteId)}/drives/${encodeURIComponent(
+    driveId
+  )}/items/${encodeURIComponent(itemId)}/createLink`;
+  try {
+    const res = await graphRequest(token, path, {
+      method: "POST",
+      headers: { "Content-Type": HTTP_CONTENT_TYPE_JSON },
+      body: JSON.stringify({
+        type: "view",
+        scope: "organization",
+      }),
+    });
+    if (!res.ok) {
+      logMySharedUrlDebug(
+        "createLink (organization view) failed",
+        `${res.status} ${await res.text()}`
+      );
+      return undefined;
+    }
+    const data = (await res.json()) as { link?: { webUrl?: string } };
+    const url = data.link?.webUrl?.trim();
+    return url || undefined;
+  } catch (e) {
+    logMySharedUrlDebug("createLink error", e);
+    return undefined;
+  }
+}
+
+async function ensureFolderPath(
+  token: string,
+  driveId: string,
+  folderPath: string
+): Promise<void> {
+  const segments = folderPath.split("/").filter(Boolean);
+  if (segments.length === 0) {
+    return;
+  }
+
+  let pathSoFar = "";
+  for (const segment of segments) {
+    pathSoFar = pathSoFar ? `${pathSoFar}/${segment}` : segment;
+    const encoded = encodeDriveRelativePath(pathSoFar);
+    const itemPath = `/drives/${encodeURIComponent(driveId)}/root:/${encoded}`;
+
+    const check = await graphRequest(token, itemPath);
+    if (check.ok) {
+      continue;
+    }
+    if (check.status !== 404) {
+      throw new Error(
+        ERR_GRAPH_FOLDER_CHECK(pathSoFar, check.status, await check.text())
+      );
+    }
+
+    const parentPath = pathSoFar.includes("/")
+      ? pathSoFar.slice(0, pathSoFar.lastIndexOf("/"))
+      : "";
+    const childrenSegment = parentPath
+      ? `root:/${encodeDriveRelativePath(parentPath)}:/children`
+      : "root/children";
+    const createPath = `/drives/${encodeURIComponent(driveId)}/${childrenSegment}`;
+
+    const created = await graphRequest(token, createPath, {
+      method: "POST",
+      headers: { "Content-Type": HTTP_CONTENT_TYPE_JSON },
+      body: JSON.stringify({
+        name: segment,
+        folder: {},
+        "@microsoft.graph.conflictBehavior": MICROSOFT_GRAPH_CONFLICT_BEHAVIOR_FAIL,
+      }),
+    });
+
+    if (created.status === 409) {
+      continue;
+    }
+    if (!created.ok) {
+      throw new Error(
+        ERR_GRAPH_CREATE_FOLDER(
+          segment,
+          parentPath,
+          created.status,
+          await created.text()
+        )
+      );
+    }
+  }
+}
+
+/**
+ * Uploads when `SHAREPOINT_SITE_HOST` resolves (params and/or env).
+ * Skips when the site host is missing.
+ */
+export type SharePointUploadSaved = {
+  skipped: false;
+  webUrl?: string;
+  /** Microsoft Graph driveItem id (opaque). */
+  driveItemId?: string;
+  /** Present for items in SharePoint document libraries. */
+  sharepointIds?: GraphDriveItemSummary["sharepointIds"];
+};
+
+export async function uploadBufferToSharePointIfConfigured(
+  buffer: Buffer,
+  filename: string,
+  overrides?: SharePointUploadOverrides
+): Promise<{ skipped: true } | SharePointUploadSaved> {
+  const cfg = resolveSiteConfig(overrides);
+  if (!cfg) {
+    return { skipped: true };
+  }
+
+  if (!cfg.clientId) {
+    throw new Error(ERR_MICROSOFT_CLIENT_ID_REQUIRED(ENTRA_DEFAULT_REDIRECT_URI));
+  }
+
+  const host = cfg.siteHost.replace(/^https?:\/\//, "");
+  const folder = cfg.folderPath
+    .replaceAll("\\", "/")
+    .replace(/^\/+|\/+$/g, "");
+
+  const token = await acquireGraphToken(
+    cfg.tenantId,
+    cfg.clientId,
+    cfg.redirectUri
+  );
+  const { siteId, driveId } = await resolveSiteAndDriveIds(
+    token,
+    host,
+    cfg.sitePath,
+    cfg.driveName
+  );
+
+  await ensureFolderPath(token, driveId, folder);
+
+  const relativeFile = folder ? `${folder}/${filename}` : filename;
+  const encodedFile = encodeDriveRelativePath(relativeFile);
+  const uploadPath = `/sites/${encodeURIComponent(siteId)}/drives/${encodeURIComponent(driveId)}/root:/${encodedFile}:/content`;
+
+  const putItem = await graphPutStream(token, uploadPath, buffer);
+  const metaItem = await getDriveItemBySiteDrivePath(
+    token,
+    siteId,
+    driveId,
+    encodedFile
+  );
+  const merged = mergeDriveItemMeta(putItem, metaItem);
+
+  let webUrl = merged.webUrl;
+  const itemId = merged.id;
+  if (itemId) {
+    const openUrl = await tryCreateOrganizationViewLink(
+      token,
+      siteId,
+      driveId,
+      itemId
+    );
+    if (openUrl) {
+      webUrl = openUrl;
+    } else if (merged.webUrl) {
+      const modern = await tryBuildSharePointMySharedDocumentUrl({
+        token,
+        siteId,
+        driveId,
+        listIdFromSharepointIds: merged.sharepointIds?.listId,
+        itemWebUrl: merged.webUrl,
+        sharePointSiteHost: cfg.siteHost,
+        tenantId: cfg.tenantId,
+      });
+      if (modern) {
+        webUrl = modern;
+      }
+    }
+  } else if (merged.webUrl) {
+    const modern = await tryBuildSharePointMySharedDocumentUrl({
+      token,
+      siteId,
+      driveId,
+      listIdFromSharepointIds: merged.sharepointIds?.listId,
+      itemWebUrl: merged.webUrl,
+      sharePointSiteHost: cfg.siteHost,
+      tenantId: cfg.tenantId,
+    });
+    if (modern) {
+      webUrl = modern;
+    }
+  }
+
+  return {
+    skipped: false,
+    webUrl,
+    driveItemId: merged.id,
+    sharepointIds: merged.sharepointIds,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+  },
+  "include": ["src/**/*.ts", "src/**/*.js", "scripts/**/*.ts"]
+}