@softeria/ms-365-mcp-server 0.3.2 → 0.3.4

package/README.md

@@ -1,213 +1,98 @@
 # ms-365-mcp-server
 
+![npm version](https://img.shields.io/npm/v/@softeria/ms-365-mcp-server.svg) ![build status](https://github.com/softeria/ms-365-mcp-server/actions/workflows/build.yml/badge.svg) ![license](https://img.shields.io/badge/license-MIT-blue.svg)
+
 Microsoft 365 MCP Server
 
 A Model Context Protocol (MCP) server for interacting with Microsoft 365 services through the Graph API.
 
-[![npm version](https://img.shields.io/npm/v/@softeria/ms-365-mcp-server.svg)](https://www.npmjs.com/package/@softeria/ms-365-mcp-server)
+## Prerequisites
+
+- Node.js >= 14
 
 ## Features
 
-- Authentication using Microsoft Authentication Library (MSAL)
+- Authentication via Microsoft Authentication Library (MSAL)
 - Excel file operations
 - Calendar event management
 - Mail operations
 - OneDrive file management
-- Dynamic tools powered by Microsoft Graph OpenAPI specification
+- Microsoft Teams integration
+- OneNote notebooks and pages
+- To Do tasks and task lists
+- Planner plans and tasks
+- SharePoint sites and lists
+- Outlook contacts
+- User and group management
+- Dynamic tools powered by Microsoft Graph OpenAPI spec
 - Built on the Model Context Protocol
 
-## Installation
-
-```bash
-npx @softeria/ms-365-mcp-server
-```
-
 ## Quick Start Example
 
-Login and test authentication in Claude Desktop:
+Test login in Claude Desktop:
 
-![MS 365 MCP Server login example in Claude Desktop](https://github.com/user-attachments/assets/936d16bc-b3e1-437b-b3f1-03c54874a816)
+![Login example](![Image](https://github.com/user-attachments/assets/e457884f-c98a-4186-9e6f-eb323ec24e0a)
 
 ## Examples
 
 ![Image](https://github.com/user-attachments/assets/1a296afb-48ed-42b0-9e7c-e685d5d1784c)
 
-
-## Integration with Claude
+## Integration
 
 ### Claude Desktop
 
 To add this MCP server to Claude Desktop:
 
-1. Launch Claude Desktop
-2. Go to Settings > MCPs
-3. Click "Add MCP"
-4. Set the following configuration:
-   - Name: `ms365` (or any name you prefer)
-   - Command: `npx @softeria/ms-365-mcp-server`
-   - Click "Add"
-
-Alternatively, you can edit Claude Desktop's configuration file directly. The location varies by platform, but you can
-find it by going to Settings > Developer > Edit Config. Add this to your configuration file:
+Edit the config file under Settings > Developer:
 
 ```json
 {
   "mcpServers": {
     "ms365": {
       "command": "npx",
-      "args": ["-y", "@softeria/ms-365-mcp-server"]
+      "args": [
+        "-y",
+        "@softeria/ms-365-mcp-server"
+      ]
     }
   }
 }
 ```
 
-### Using Claude Code CLI
-
-You can add the server to Claude Code CLI using this command:
+### Claude Code CLI
 
 ```bash
 claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server
 ```
 
-For other Claude interfaces that support MCPs, please refer to their respective documentation for the correct
+For other interfaces that support MCPs, please refer to their respective documentation for the correct
 integration method.
 
-## Usage
-
-### Command Line Options
-
-```bash
-npx @softeria/ms-365-mcp-server [options]
-```
-
-Options:
-
-- `--login`: Force login using device code flow and verify Graph API access
-- `--logout`: Log out and clear saved credentials
-- `--verify-login`: Test current authentication and verify Graph API access without starting the server
-- `-v`: Enable verbose logging
-
 ### Authentication
 
-**Important:** You must authenticate before using the MCP server. There are two ways to authenticate:
-
-1. Running the server with the `--login` flag:
+> ⚠️ You must authenticate before using tools.
 
+1. **MCP client login**:
+    - Call the `login` tool (auto-checks existing token)
+    - If needed, get URL+code, visit in browser
+    - Use `verify-login` tool to confirm
+    -
+2. **Optional CLI login**:
    ```bash
    npx @softeria/ms-365-mcp-server --login
    ```
+   Follow the URL and code prompt in terminal.
 
-   This will display the login URL and code in the terminal.
-
-2. When using Claude Code or other MCP clients, use the login tools:
-   - First use the `login` tool, which will automatically check if you're already logged in
-   - If not already logged in, it will return the login URL and code
-   - Visit the URL and enter the code in your browser
-   - Then use the `verify-login` tool to check if the login was successful
-   - To force a new login even if already authenticated, use the `login` tool with `force: true`
-
-Both methods trigger the device code flow authentication, but they handle the UI interaction differently:
+Tokens are cached securely in your OS credential store (fallback to file).
 
-- CLI version displays the instructions directly in the terminal
-- MCP tool version returns the instructions as data that can be shown in the client UI
-
-You can verify your authentication status with the `--verify-login` flag, which will check if your token can successfully
-fetch user data from Microsoft Graph API:
-
-```bash
-npx @softeria/ms-365-mcp-server --verify-login
-```
-
-Both `--login` and `--verify-login` will return a JSON response that includes your basic user information from Microsoft
-Graph API if authentication is successful:
-
-```json
-{
-  "success": true,
-  "message": "Login successful",
-  "userData": {
-    "displayName": "Your Name",
-    "userPrincipalName": "your.email@example.com"
-  }
-}
-```
+## Tools
 
-Authentication tokens are cached securely in your system's credential store with fallback to file storage if needed.
-
-### MCP Tools
-
-This server provides several MCP tools for interacting with Microsoft 365 services, including:
-
-- Authentication (login, logout)
-- Files/OneDrive management
-- Excel operations:
-  - List worksheets
-  - Get cell range values
-  - Format cell ranges
-  - Sort data
-  - Create charts
-- Calendar management
-- Mail operations
-
-For a complete list of available tools and their parameters, use an MCP-enabled Claude interface and explore the available tools.
-
-## For Developers
-
-### Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/softeria/ms-365-mcp-server.git
-cd ms-365-mcp-server
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-```
-
-### OpenAPI Integration
-
-This project uses the Microsoft Graph OpenAPI specification to dynamically generate MCP tools. During installation, the OpenAPI specification is automatically downloaded from Microsoft Graph's GitHub repository.
-
-To manually download the latest OpenAPI spec:
-
-```bash
-# Download the latest OpenAPI spec from Microsoft Graph
-npm run download-openapi
-```
-
-### GitHub Actions
-
-This repository uses GitHub Actions for continuous integration and deployment:
-
-- **Build Workflow**: Runs on all pushes to main and pull requests. Verifies the project builds successfully and passes
-  all tests.
-- **Publish Workflow**: Automatically publishes to npm when a new GitHub release is created.
-
-[![Build Status](https://github.com/softeria/ms-365-mcp-server/actions/workflows/build.yml/badge.svg)](https://github.com/softeria/ms-365-mcp-server/actions/workflows/build.yml)
-
-### Release Process
-
-To create a new release:
-
-```bash
-# Default (patch version): 0.1.11 -> 0.1.12
-npm run release
-
-# Minor version: 0.1.11 -> 0.2.0
-npm run release minor
-
-# Major version: 0.1.11 -> 1.0.0
-npm run release major
-```
+- **Authentication:** `login`, `logout`, `verify-login`
+- **Excel:** list worksheets, get/set ranges, format, sort, chart
+- **Calendar:** list/create/update/delete events
+- **Mail:** send, read, delete messages
+- **OneDrive:** upload, download, list files
 
-This script will:
+## License
 
-1. Run tests to verify everything works
-2. Bump the version number according to the specified type (patch by default)
-3. Commit the version changes
-4. Push to GitHub
-5. Create a GitHub release
-6. Trigger the publishing workflow to publish to npm
+MIT © 2025 Softeria

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Microsoft 365 MCP Server",
   "type": "module",
   "main": "index.mjs",

package/src/auth.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import path from 'path';
 import fs from 'fs';
 import logger from './logger.mjs';
+import { TARGET_ENDPOINTS } from './dynamic-tools.mjs';
 
 const SERVICE_NAME = 'ms-365-mcp-server';
 const TOKEN_CACHE_ACCOUNT = 'msal-token-cache';
@@ -17,17 +18,36 @@ const DEFAULT_CONFIG = {
   },
 };
 
-const DEFAULT_SCOPES = [
-  'Files.ReadWrite',
-  'User.Read',
-  'Calendars.Read',
-  'Calendars.ReadWrite',
-  'Mail.Read',
-  'Mail.ReadWrite',
-];
+const SCOPE_HIERARCHY = {
+  'Mail.ReadWrite': ['Mail.Read', 'Mail.Send'],
+  'Calendars.ReadWrite': ['Calendars.Read'],
+  'Files.ReadWrite': ['Files.Read'],
+  'Tasks.ReadWrite': ['Tasks.Read'],
+  'Contacts.ReadWrite': ['Contacts.Read'],
+};
+
+function buildScopesFromEndpoints() {
+  const scopesSet = new Set();
+
+  TARGET_ENDPOINTS.forEach((endpoint) => {
+    if (endpoint.scopes && Array.isArray(endpoint.scopes)) {
+      endpoint.scopes.forEach((scope) => scopesSet.add(scope));
+    }
+  });
+
+  Object.entries(SCOPE_HIERARCHY).forEach(([higherScope, lowerScopes]) => {
+    if (lowerScopes.every((scope) => scopesSet.has(scope))) {
+      lowerScopes.forEach((scope) => scopesSet.delete(scope));
+      scopesSet.add(higherScope);
+    }
+  });
+
+  return Array.from(scopesSet);
+}
 
 class AuthManager {
-  constructor(config = DEFAULT_CONFIG, scopes = DEFAULT_SCOPES) {
+  constructor(config = DEFAULT_CONFIG, scopes = buildScopesFromEndpoints()) {
+    logger.info(`And scopes are ${scopes.join(', ')}`, scopes);
     this.config = config;
     this.scopes = scopes;
     this.msalApp = new PublicClientApplication(this.config);

package/src/dynamic-tools.mjs

@@ -6,136 +6,337 @@ import {
   isMethodWithBody,
   loadOpenApiSpec,
 } from './openapi-helpers.mjs';
+import { z } from 'zod';
+
+/**
+ * Validates all endpoints in TARGET_ENDPOINTS against the OpenAPI spec.
+ * Returns an array of endpoints that don't exist in the spec.
+ *
+ * @returns {Array} Array of missing endpoints
+ */
+export function validateEndpoints() {
+  const openapi = loadOpenApiSpec();
+  const missingEndpoints = [];
+
+  for (const endpoint of TARGET_ENDPOINTS) {
+    const result = findPathAndOperation(openapi, endpoint.pathPattern, endpoint.method);
+    if (!result) {
+      missingEndpoints.push({
+        toolName: endpoint.toolName,
+        pathPattern: endpoint.pathPattern,
+        method: endpoint.method,
+      });
+    }
+  }
+
+  return missingEndpoints;
+}
 
 export const TARGET_ENDPOINTS = [
   {
     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/messages',
+    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: '/users/{user-id}/drive',
+    pathPattern: '/me/calendars',
     method: 'get',
-    toolName: 'get-user-drive',
+    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',
     method: 'post',
     toolName: 'create-item-in-folder',
+    scopes: ['Files.ReadWrite'],
   },
   {
     pathPattern: '/drives/{drive-id}/items/{driveItem-id}/children/{driveItem-id1}/content',
     method: 'get',
-    toolName: 'download-file-content',
+    toolName: 'download-onedrive-file-content',
+    scopes: ['Files.Read'],
   },
   {
     pathPattern: '/drives/{drive-id}/items/{driveItem-id}',
     method: 'delete',
-    toolName: 'delete-file',
+    toolName: 'delete-onedrive-file',
+    scopes: ['Files.ReadWrite'],
   },
   {
     pathPattern: '/drives/{drive-id}/items/{driveItem-id}',
     method: 'patch',
-    toolName: 'update-file-metadata',
+    toolName: 'update-onedrive-file-metadata',
+    scopes: ['Files.ReadWrite'],
   },
+
   {
     pathPattern:
       '/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/charts/add',
     method: 'post',
-    toolName: 'create-chart',
+    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-range',
+    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-range',
+    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-range',
+    toolName: 'get-excel-range',
     isExcelOp: true,
+    scopes: ['Files.Read'],
   },
   {
     pathPattern: '/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets',
     method: 'get',
-    toolName: 'list-worksheets',
+    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'],
   },
 ];
 
@@ -144,6 +345,16 @@ export async function registerDynamicTools(server, graphClient) {
     const openapi = loadOpenApiSpec();
     logger.info('Generating dynamic tools from OpenAPI spec...');
 
+    const missingEndpoints = validateEndpoints();
+    if (missingEndpoints.length > 0) {
+      logger.warn('Some endpoints are missing from the OpenAPI spec:');
+      missingEndpoints.forEach((endpoint) => {
+        logger.warn(
+          `- Tool: ${endpoint.toolName}, Path: ${endpoint.pathPattern}, Method: ${endpoint.method}`
+        );
+      });
+    }
+
     for (const endpoint of TARGET_ENDPOINTS) {
       const result = findPathAndOperation(openapi, endpoint.pathPattern, endpoint.method);
       if (!result) continue;
@@ -157,13 +368,13 @@ export async function registerDynamicTools(server, graphClient) {
       const paramsSchema = buildParameterSchemas(endpoint, operation);
 
       if (endpoint.hasCustomParams) {
-        if (endpoint.toolName === 'upload-file') {
+        if (endpoint.toolName === 'upload-onedrive-file') {
           paramsSchema.content = z.string().describe('File content to upload');
           paramsSchema.contentType = z
             .string()
             .optional()
             .describe('Content type of the file (e.g., "application/pdf", "image/jpeg")');
-        } else if (endpoint.toolName === 'create-folder') {
+        } else if (endpoint.toolName === 'create-onedrive-folder') {
           paramsSchema.name = z.string().describe('Name of the folder to create');
           paramsSchema.description = z.string().optional().describe('Description of the folder');
         }
@@ -193,13 +404,13 @@ export async function registerDynamicTools(server, graphClient) {
           options.excelFile = params.filePath;
         }
 
-        if (endpoint.toolName === 'download-file') {
+        if (endpoint.toolName === 'download-onedrive-file-content') {
           options.rawResponse = true;
         }
 
         const url = buildRequestUrl(endpoint.pathPattern, params, pathParams, operation.parameters);
 
-        if (endpoint.toolName === 'upload-file' && params.content) {
+        if (endpoint.toolName === 'upload-onedrive-file' && params.content) {
           options.body = params.content;
           options.headers = {
             'Content-Type': params.contentType || 'application/octet-stream',

package/test/mappings.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { validateEndpoints } from '../src/dynamic-tools.mjs';
+
+/**
+ * This test file ensures that all the mappings in TARGET_ENDPOINTS actually match
+ * the endpoints in the OpenAPI spec. It helps catch issues where:
+ *
+ * 1. An endpoint in TARGET_ENDPOINTS doesn't exist in the OpenAPI spec
+ * 2. The method for an endpoint doesn't match what's in the OpenAPI spec
+ *
+ * This is a more automated approach than manually running the app and tailing logs.
+ */
+
+describe('Mappings Validation', () => {
+  it('should verify all TARGET_ENDPOINTS exist in the OpenAPI spec', () => {
+    const missingEndpoints = validateEndpoints();
+
+    if (missingEndpoints.length > 0) {
+      console.error('The following endpoints are missing from the OpenAPI spec:');
+      missingEndpoints.forEach((endpoint) => {
+        console.error(
+          `- Tool: ${endpoint.toolName}, Path: ${endpoint.pathPattern}, Method: ${endpoint.method}`
+        );
+      });
+    }
+
+    expect(missingEndpoints).toEqual([]);
+  });
+});