@softeria/ms-365-mcp-server 0.3.5 → 0.4.0

package/src/{auth.mjs → auth.ts}

@@ -1,24 +1,32 @@
 import { PublicClientApplication } from '@azure/msal-node';
+import type { Configuration } from '@azure/msal-node';
 import keytar from 'keytar';
 import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
-import logger from './logger.mjs';
-import { TARGET_ENDPOINTS } from './dynamic-tools.mjs';
+import logger from './logger.js';
+
+const endpoints = await import('./endpoints.json', {
+  assert: { type: 'json' },
+});
 
 const SERVICE_NAME = 'ms-365-mcp-server';
 const TOKEN_CACHE_ACCOUNT = 'msal-token-cache';
 const FALLBACK_DIR = path.dirname(fileURLToPath(import.meta.url));
 const FALLBACK_PATH = path.join(FALLBACK_DIR, '..', '.token-cache.json');
 
-const DEFAULT_CONFIG = {
+const DEFAULT_CONFIG: Configuration = {
   auth: {
     clientId: '084a3e9f-a9f4-43f7-89f9-d229cf97853e',
     authority: 'https://login.microsoftonline.com/common',
   },
 };
 
-const SCOPE_HIERARCHY = {
+interface ScopeHierarchy {
+  [key: string]: string[];
+}
+
+const SCOPE_HIERARCHY: ScopeHierarchy = {
   'Mail.ReadWrite': ['Mail.Read', 'Mail.Send'],
   'Calendars.ReadWrite': ['Calendars.Read'],
   'Files.ReadWrite': ['Files.Read'],
@@ -26,10 +34,10 @@ const SCOPE_HIERARCHY = {
   'Contacts.ReadWrite': ['Contacts.Read'],
 };
 
-function buildScopesFromEndpoints() {
-  const scopesSet = new Set();
+function buildScopesFromEndpoints(): string[] {
+  const scopesSet = new Set<string>();
 
-  TARGET_ENDPOINTS.forEach((endpoint) => {
+  endpoints.default.forEach((endpoint) => {
     if (endpoint.scopes && Array.isArray(endpoint.scopes)) {
       endpoint.scopes.forEach((scope) => scopesSet.add(scope));
     }
@@ -45,8 +53,26 @@ function buildScopesFromEndpoints() {
   return Array.from(scopesSet);
 }
 
+interface LoginTestResult {
+  success: boolean;
+  message: string;
+  userData?: {
+    displayName: string;
+    userPrincipalName: string;
+  };
+}
+
 class AuthManager {
-  constructor(config = DEFAULT_CONFIG, scopes = buildScopesFromEndpoints()) {
+  private config: Configuration;
+  private scopes: string[];
+  private msalApp: PublicClientApplication;
+  private accessToken: string | null;
+  private tokenExpiry: number | null;
+
+  constructor(
+    config: Configuration = DEFAULT_CONFIG,
+    scopes: string[] = buildScopesFromEndpoints()
+  ) {
     logger.info(`And scopes are ${scopes.join(', ')}`, scopes);
     this.config = config;
     this.scopes = scopes;
@@ -55,9 +81,9 @@ class AuthManager {
     this.tokenExpiry = null;
   }
 
-  async loadTokenCache() {
+  async loadTokenCache(): Promise<void> {
     try {
-      let cacheData;
+      let cacheData: string | undefined;
 
       try {
         const cachedData = await keytar.getPassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT);
@@ -65,7 +91,9 @@ class AuthManager {
           cacheData = cachedData;
         }
       } catch (keytarError) {
-        logger.warn(`Keychain access failed, falling back to file storage: ${keytarError.message}`);
+        logger.warn(
+          `Keychain access failed, falling back to file storage: ${(keytarError as Error).message}`
+        );
       }
 
       if (!cacheData && fs.existsSync(FALLBACK_PATH)) {
@@ -76,27 +104,29 @@ class AuthManager {
         this.msalApp.getTokenCache().deserialize(cacheData);
       }
     } catch (error) {
-      logger.error(`Error loading token cache: ${error.message}`);
+      logger.error(`Error loading token cache: ${(error as Error).message}`);
     }
   }
 
-  async saveTokenCache() {
+  async saveTokenCache(): Promise<void> {
     try {
       const cacheData = this.msalApp.getTokenCache().serialize();
 
       try {
         await keytar.setPassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT, cacheData);
       } catch (keytarError) {
-        logger.warn(`Keychain save failed, falling back to file storage: ${keytarError.message}`);
+        logger.warn(
+          `Keychain save failed, falling back to file storage: ${(keytarError as Error).message}`
+        );
 
         fs.writeFileSync(FALLBACK_PATH, cacheData);
       }
     } catch (error) {
-      logger.error(`Error saving token cache: ${error.message}`);
+      logger.error(`Error saving token cache: ${(error as Error).message}`);
     }
   }
 
-  async getToken(forceRefresh = false) {
+  async getToken(forceRefresh = false): Promise<string | null> {
     if (this.accessToken && this.tokenExpiry && this.tokenExpiry > Date.now() && !forceRefresh) {
       return this.accessToken;
     }
@@ -112,7 +142,7 @@ class AuthManager {
       try {
         const response = await this.msalApp.acquireTokenSilent(silentRequest);
         this.accessToken = response.accessToken;
-        this.tokenExpiry = new Date(response.expiresOn).getTime();
+        this.tokenExpiry = response.expiresOn ? new Date(response.expiresOn).getTime() : null;
         return this.accessToken;
       } catch (error) {
         logger.info('Silent token acquisition failed, using device code flow');
@@ -122,10 +152,10 @@ class AuthManager {
     throw new Error('No valid token found');
   }
 
-  async acquireTokenByDeviceCode(hack) {
+  async acquireTokenByDeviceCode(hack?: (message: string) => void): Promise<string | null> {
     const deviceCodeRequest = {
       scopes: this.scopes,
-      deviceCodeCallback: (response) => {
+      deviceCodeCallback: (response: { message: string }) => {
         const text = ['\n', response.message, '\n'].join('');
         if (hack) {
           hack(text + 'After login run the "verify login" command');
@@ -140,17 +170,17 @@ class AuthManager {
       logger.info('Requesting device code...');
       const response = await this.msalApp.acquireTokenByDeviceCode(deviceCodeRequest);
       logger.info('Device code login successful');
-      this.accessToken = response.accessToken;
-      this.tokenExpiry = new Date(response.expiresOn).getTime();
+      this.accessToken = response?.accessToken || null;
+      this.tokenExpiry = response?.expiresOn ? new Date(response.expiresOn).getTime() : null;
       await this.saveTokenCache();
       return this.accessToken;
     } catch (error) {
-      logger.error(`Error in device code flow: ${error.message}`);
+      logger.error(`Error in device code flow: ${(error as Error).message}`);
       throw error;
     }
   }
 
-  async testLogin() {
+  async testLogin(): Promise<LoginTestResult> {
     try {
       logger.info('Testing login...');
       const token = await this.getToken();
@@ -192,22 +222,22 @@ class AuthManager {
           };
         }
       } catch (graphError) {
-        logger.error(`Error fetching user data: ${graphError.message}`);
+        logger.error(`Error fetching user data: ${(graphError as Error).message}`);
         return {
           success: false,
-          message: `Login successful but Graph API access failed: ${graphError.message}`,
+          message: `Login successful but Graph API access failed: ${(graphError as Error).message}`,
         };
       }
     } catch (error) {
-      logger.error(`Login test failed: ${error.message}`);
+      logger.error(`Login test failed: ${(error as Error).message}`);
       return {
         success: false,
-        message: `Login failed: ${error.message}`,
+        message: `Login failed: ${(error as Error).message}`,
       };
     }
   }
 
-  async logout() {
+  async logout(): Promise<boolean> {
     try {
       const accounts = await this.msalApp.getTokenCache().getAllAccounts();
       for (const account of accounts) {
@@ -219,7 +249,7 @@ class AuthManager {
       try {
         await keytar.deletePassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT);
       } catch (keytarError) {
-        logger.warn(`Keychain deletion failed: ${keytarError.message}`);
+        logger.warn(`Keychain deletion failed: ${(keytarError as Error).message}`);
       }
 
       if (fs.existsSync(FALLBACK_PATH)) {
@@ -228,7 +258,7 @@ class AuthManager {
 
       return true;
     } catch (error) {
-      logger.error(`Error during logout: ${error.message}`);
+      logger.error(`Error during logout: ${(error as Error).message}`);
       throw error;
     }
   }

package/src/{cli.mjs → cli.ts}

@@ -19,7 +19,15 @@ program
   .option('--logout', 'Log out and clear saved credentials')
   .option('--verify-login', 'Verify login without starting the server');
 
-export function parseArgs() {
+export interface CommandOptions {
+  v?: boolean;
+  login?: boolean;
+  logout?: boolean;
+  verifyLogin?: boolean;
+  [key: string]: any;
+}
+
+export function parseArgs(): CommandOptions {
   program.parse();
   return program.opts();
 }

package/src/endpoints.json

@@ -0,0 +1,375 @@
+[
+  {
+    "pathPattern": "/me/messages",
+    "method": "get",
+    "toolName": "list-mail-messages",
+    "scopes": [
+      "Mail.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/mailFolders",
+    "method": "get",
+    "toolName": "list-mail-folders",
+    "scopes": [
+      "Mail.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/mailFolders/{mailFolder-id}/messages",
+    "method": "get",
+    "toolName": "list-mail-folder-messages",
+    "scopes": [
+      "Mail.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/messages/{message-id}",
+    "method": "get",
+    "toolName": "get-mail-message",
+    "scopes": [
+      "Mail.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/sendMail",
+    "method": "post",
+    "toolName": "send-mail",
+    "scopes": [
+      "Mail.Send"
+    ]
+  },
+  {
+    "pathPattern": "/me/messages/{message-id}",
+    "method": "delete",
+    "toolName": "delete-mail-message",
+    "scopes": [
+      "Mail.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/events",
+    "method": "get",
+    "toolName": "list-calendar-events",
+    "scopes": [
+      "Calendars.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/events/{event-id}",
+    "method": "get",
+    "toolName": "get-calendar-event",
+    "scopes": [
+      "Calendars.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/events",
+    "method": "post",
+    "toolName": "create-calendar-event",
+    "scopes": [
+      "Calendars.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/events/{event-id}",
+    "method": "patch",
+    "toolName": "update-calendar-event",
+    "scopes": [
+      "Calendars.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/events/{event-id}",
+    "method": "delete",
+    "toolName": "delete-calendar-event",
+    "scopes": [
+      "Calendars.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/calendarView",
+    "method": "get",
+    "toolName": "get-calendar-view",
+    "scopes": [
+      "Calendars.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/calendars",
+    "method": "get",
+    "toolName": "list-calendars",
+    "scopes": [
+      "Calendars.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives",
+    "method": "get",
+    "toolName": "list-drives",
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/root",
+    "method": "get",
+    "toolName": "get-drive-root-item",
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/root",
+    "method": "get",
+    "toolName": "get-root-folder",
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/children",
+    "method": "get",
+    "toolName": "list-folder-files",
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/children/{driveItem-id1}/content",
+    "method": "get",
+    "toolName": "download-onedrive-file-content",
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
+    "method": "delete",
+    "toolName": "delete-onedrive-file",
+    "scopes": [
+      "Files.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/charts/add",
+    "method": "post",
+    "toolName": "create-excel-chart",
+    "isExcelOp": true,
+    "scopes": [
+      "Files.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range()/format",
+    "method": "patch",
+    "toolName": "format-excel-range",
+    "isExcelOp": true,
+    "scopes": [
+      "Files.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range()/sort",
+    "method": "patch",
+    "toolName": "sort-excel-range",
+    "isExcelOp": true,
+    "scopes": [
+      "Files.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')",
+    "method": "get",
+    "toolName": "get-excel-range",
+    "isExcelOp": true,
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets",
+    "method": "get",
+    "toolName": "list-excel-worksheets",
+    "isExcelOp": true,
+    "scopes": [
+      "Files.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/onenote/notebooks",
+    "method": "get",
+    "toolName": "list-onenote-notebooks",
+    "scopes": [
+      "Notes.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/onenote/notebooks/{notebook-id}/sections",
+    "method": "get",
+    "toolName": "list-onenote-notebook-sections",
+    "scopes": [
+      "Notes.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/onenote/notebooks/{notebook-id}/sections/{onenoteSection-id}/pages",
+    "method": "get",
+    "toolName": "list-onenote-section-pages",
+    "scopes": [
+      "Notes.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/onenote/pages/{onenotePage-id}/content",
+    "method": "get",
+    "toolName": "get-onenote-page-content",
+    "scopes": [
+      "Notes.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/onenote/pages",
+    "method": "post",
+    "toolName": "create-onenote-page",
+    "scopes": [
+      "Notes.Create"
+    ]
+  },
+  {
+    "pathPattern": "/me/todo/lists",
+    "method": "get",
+    "toolName": "list-todo-task-lists",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/todo/lists/{todoTaskList-id}/tasks",
+    "method": "get",
+    "toolName": "list-todo-tasks",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/todo/lists/{todoTaskList-id}/tasks/{todoTask-id}",
+    "method": "get",
+    "toolName": "get-todo-task",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/todo/lists/{todoTaskList-id}/tasks",
+    "method": "post",
+    "toolName": "create-todo-task",
+    "scopes": [
+      "Tasks.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/todo/lists/{todoTaskList-id}/tasks/{todoTask-id}",
+    "method": "patch",
+    "toolName": "update-todo-task",
+    "scopes": [
+      "Tasks.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/todo/lists/{todoTaskList-id}/tasks/{todoTask-id}",
+    "method": "delete",
+    "toolName": "delete-todo-task",
+    "scopes": [
+      "Tasks.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/planner/tasks",
+    "method": "get",
+    "toolName": "list-planner-tasks",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/planner/plans/{plannerPlan-id}",
+    "method": "get",
+    "toolName": "get-planner-plan",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/planner/plans/{plannerPlan-id}/tasks",
+    "method": "get",
+    "toolName": "list-plan-tasks",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}",
+    "method": "get",
+    "toolName": "get-planner-task",
+    "scopes": [
+      "Tasks.Read"
+    ]
+  },
+  {
+    "pathPattern": "/planner/tasks",
+    "method": "post",
+    "toolName": "create-planner-task",
+    "scopes": [
+      "Tasks.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/contacts",
+    "method": "get",
+    "toolName": "list-outlook-contacts",
+    "scopes": [
+      "Contacts.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/contacts/{contact-id}",
+    "method": "get",
+    "toolName": "get-outlook-contact",
+    "scopes": [
+      "Contacts.Read"
+    ]
+  },
+  {
+    "pathPattern": "/me/contacts",
+    "method": "post",
+    "toolName": "create-outlook-contact",
+    "scopes": [
+      "Contacts.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/contacts/{contact-id}",
+    "method": "patch",
+    "toolName": "update-outlook-contact",
+    "scopes": [
+      "Contacts.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me/contacts/{contact-id}",
+    "method": "delete",
+    "toolName": "delete-outlook-contact",
+    "scopes": [
+      "Contacts.ReadWrite"
+    ]
+  },
+  {
+    "pathPattern": "/me",
+    "method": "get",
+    "toolName": "get-current-user",
+    "scopes": [
+      "User.Read"
+    ]
+  }
+]

package/src/generated/README.md

@@ -0,0 +1,51 @@
+# MS 365 OpenAPI Client Generation
+
+This directory contains the generated TypeScript client for the Microsoft 365 API based on the OpenAPI specification.
+
+## The Evolution
+
+### Initial Challenge
+
+Our initial approach used the full MS 365 OpenAPI specification file directly. This created two significant problems:
+
+- The spec file was a whopping 45MB in size
+- It had to be included in the npm package
+- Startup time was painfully slow due to parsing the large spec file
+
+### Exploration Phase
+
+We explored several alternatives:
+
+1. Live-parsing a trimmed version of the spec file
+2. Creating a static trimmed version
+3. Pre-generating client code
+
+### Current Solution
+
+We eventually settled on a combined approach:
+
+- Trim the OpenAPI spec to only what we need
+- Generate static TypeScript client code using [openapi-zod-client](https://github.com/astahmer/openapi-zod-client)
+
+### Benefits
+
+- **Dramatically faster startup time** - No need to parse a large spec file
+- **Significantly smaller package size** - No more bundling a 45MB spec file
+- **Type safety** - Full TypeScript types generated from the OpenAPI spec
+- **Validation** - Zod schemas for request/response validation
+
+## Regenerating the Client
+
+To regenerate the client code (e.g., after API changes or to update the supported endpoints):
+
+```
+npm run bin/generate-graph-client.mjs
+```
+
+This command does the following:
+
+1. Fetches/processes the OpenAPI spec
+2. Generates the TypeScript client with Zod validation
+3. Outputs the result to `client.ts` in this directory
+
+No complex build scripts needed - the generation is handled by openapi-zod-client.