@softeria/ms-365-mcp-server 0.2.0 → 0.3.0

package/README.md

@@ -4,20 +4,16 @@ Microsoft 365 MCP Server
 
 A Model Context Protocol (MCP) server for interacting with Microsoft 365 services through the Graph API.
 
-[![Build Status](https://github.com/softeria-eu/ms-365-mcp-server/actions/workflows/build.yml/badge.svg)](https://github.com/softeria-eu/ms-365-mcp-server/actions/workflows/build.yml)
 [![npm version](https://img.shields.io/npm/v/@softeria/ms-365-mcp-server.svg)](https://www.npmjs.com/package/@softeria/ms-365-mcp-server)
 
 ## Features
 
 - Authentication using Microsoft Authentication Library (MSAL)
-- Excel file operations:
-    - Update cell values
-    - Create and manage charts
-    - Format cells
-    - Sort data
-    - Create tables
-    - Read cell values
-    - List worksheets
+- Excel file operations
+- Calendar event management
+- Mail operations
+- OneDrive file management
+- Dynamic tools powered by Microsoft Graph OpenAPI specification
 - Built on the Model Context Protocol
 
 ## Installation
@@ -26,15 +22,18 @@ A Model Context Protocol (MCP) server for interacting with Microsoft 365 service
 npx @softeria/ms-365-mcp-server
 ```
 
-## Integration with Claude
+## Quick Start Example
 
-### Claude Code CLI
+Login and test authentication in Claude Desktop:
 
-To add this MCP server to Claude Code CLI:
+![MS 365 MCP Server login example in Claude Desktop](https://github.com/user-attachments/assets/936d16bc-b3e1-437b-b3f1-03c54874a816)
 
-```bash
-claude mcp add ms -- npx @softeria/ms-365-mcp-server
-```
+## Examples
+
+![Image](https://github.com/user-attachments/assets/1a296afb-48ed-42b0-9e7c-e685d5d1784c)
+
+
+## Integration with Claude
 
 ### Claude Desktop
 
@@ -44,68 +43,34 @@ To add this MCP server to Claude Desktop:
 2. Go to Settings > MCPs
 3. Click "Add MCP"
 4. Set the following configuration:
-    - Name: `ms` (or any name you prefer)
-    - Command: `npx @softeria/ms-365-mcp-server`
-    - Click "Add"
-
-### Direct Configuration
+   - Name: `ms365` (or any name you prefer)
+   - Command: `npx @softeria/ms-365-mcp-server`
+   - Click "Add"
 
-You can also use this configuration JSON in compatible Claude interfaces:
+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:
 
 ```json
 {
-  "name": "ms",
-  "command": "npx @softeria/ms-365-mcp-server"
+  "mcpServers": {
+    "ms365": {
+      "command": "npx",
+      "args": ["-y", "@softeria/ms-365-mcp-server"]
+    }
+  }
 }
 ```
 
-## Development
+### Using Claude Code CLI
 
-### Setup
+You can add the server to Claude Code CLI using this command:
 
 ```bash
-# Clone the repository
-git clone https://github.com/softeria-eu/ms-365-mcp-server.git
-cd ms-365-mcp-server
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
+claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server
 ```
 
-### 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.
-
-### 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
-```
-
-This script will:
-
-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
+For other Claude interfaces that support MCPs, please refer to their respective documentation for the correct
+integration method.
 
 ## Usage
 
@@ -119,7 +84,7 @@ Options:
 
 - `--login`: Force login using device code flow and verify Graph API access
 - `--logout`: Log out and clear saved credentials
-- `--test-login`: Test current authentication and verify Graph API access without starting the server
+- `--verify-login`: Test current authentication and verify Graph API access without starting the server
 - `-v`: Enable verbose logging
 
 ### Authentication
@@ -127,29 +92,33 @@ Options:
 **Important:** You must authenticate before using the MCP server. There are two ways to authenticate:
 
 1. Running the server with the `--login` flag:
+
    ```bash
    npx @softeria/ms-365-mcp-server --login
    ```
+
    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 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
+   - 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:
 
 - 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 `--test-login` flag, which will check if your token can successfully
+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 --test-login
+npx @softeria/ms-365-mcp-server --verify-login
 ```
 
-Both `--login` and `--test-login` will return a JSON response that includes your basic user information from Microsoft
+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
@@ -167,77 +136,78 @@ Authentication tokens are cached securely in your system's credential store with
 
 ### MCP Tools
 
-This server provides several MCP tools for interacting with Microsoft 365 services:
-
-#### Authentication Tools
-
-- `login`: Start a new login process with Microsoft (returns login URL and code)
-- `verify-login`: Check if login was completed successfully and verify Graph API access
-- `logout`: Log out of Microsoft and clear credentials
-- `test-login`: Test current authentication status and verify Graph API access
-
-#### Files/OneDrive Tools
-
-- `list-files`: List files and folders in a specified path
-- `get-file`: Get details of a specific file
-- `create-folder`: Create a new folder
-- `delete-item`: Delete a file or folder
-- `copy-item`: Copy a file or folder to a new location
-- `move-item`: Move a file or folder to a new location
-- `rename-item`: Rename a file or folder
-- `search-files`: Search for files matching a query
-- `get-shared-items`: Get a list of items shared with you
-- `create-sharing-link`: Create a sharing link for a file or folder
-- `get-file-content`: Get the content of a file
-
-#### Excel Tools
-
-All Excel tools require a `filePath` parameter to specify which Excel file to operate on. You can use the Files tools to
-find and manage your Excel files.
-
-- `update-excel`: Update cell values in an Excel worksheet
-- `create-chart`: Create a chart in an Excel worksheet
-- `format-range`: Apply formatting to a range of cells
-- `sort-range`: Sort a range of cells
-- `create-table`: Create a table from a range of cells
-- `get-range`: Get values from a range of cells
-- `list-worksheets`: List all worksheets in the workbook
-- `close-session`: Close the session for a specific Excel file
-- `close-all-sessions`: Close all active Excel sessions
-- `delete-chart`: Delete a chart from a worksheet
-- `get-charts`: Get all charts in a worksheet
-
-Example workflow:
-
-1. Use `list-files` to find Excel files in your OneDrive
-2. Use `list-worksheets` with the file path to see available worksheets
-3. Use `get-range` to retrieve data from the Excel file
-4. Use other Excel tools to manipulate the file as needed
-
-#### Calendar Tools
-
-Tools for working with Outlook calendars.
-
-- `list-calendars`: List all calendars
-- `get-default-calendar`: Get information about the default calendar
-- `list-events`: List events from a calendar with optional filtering, sorting, and date ranges
-- `get-detailed-events`: Get events with expanded properties and options to include body, attendees, extensions, etc.
-- `get-event`: Get detailed information about a specific calendar event
-- `create-event`: Create a new calendar event with comprehensive options (sensitivity, importance, free/busy status,
-  optional attendees, reminders, online meetings, categories)
-- `create-recurring-event`: Create recurring events (daily, weekly, monthly, yearly) with the same comprehensive options
-  and flexible recurrence patterns
-- `update-event`: Update an existing calendar event
-- `delete-event`: Delete a calendar event
-- `accept-event`: Accept a calendar meeting invitation
-- `decline-event`: Decline a calendar meeting invitation
-- `tentatively-accept-event`: Tentatively accept a calendar meeting invitation
-- `find-meeting-times`: Find available meeting times for a set of attendees
-- `get-schedules`: Get availability information for multiple users or resource rooms
-
-#### Mail Tools
-
-Tools for working with Outlook email.
-
-- `list-messages`: List emails from any mail folder with powerful filtering, searching, and sorting options
-- `get-message`: Get detailed information about a specific email message with options to include attachments and other metadata
+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-eu/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-eu/ms-365-mcp-server/actions/workflows/build.yml/badge.svg)](https://github.com/softeria-eu/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
+```
+
+This script will:
+
+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

package/bin/download-openapi.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const args = process.argv.slice(2);
+const forceDownload = args.includes('--force');
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const targetDir = path.resolve(__dirname, '..', 'openapi');
+const targetFile = path.join(targetDir, 'openapi.yaml');
+
+const openapiUrl =
+  'https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/refs/heads/master/openapi/v1.0/openapi.yaml';
+
+async function downloadOpenApi() {
+  if (!fs.existsSync(targetDir)) {
+    console.log(`Creating directory: ${targetDir}`);
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  if (fs.existsSync(targetFile) && !forceDownload) {
+    console.log(`OpenAPI specification already exists at ${targetFile}`);
+    console.log('Use --force to download again');
+    return;
+  }
+
+  console.log(`Downloading OpenAPI specification from ${openapiUrl}`);
+
+  try {
+    const response = await fetch(openapiUrl);
+
+    if (!response.ok) {
+      throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+    }
+
+    const content = await response.text();
+    fs.writeFileSync(targetFile, content);
+    console.log(`OpenAPI specification downloaded to ${targetFile}`);
+  } catch (error) {
+    console.error('Error downloading OpenAPI specification:', error.message);
+    process.exit(1);
+  }
+}
+
+downloadOpenApi();

package/bin/release.mjs

@@ -3,6 +3,33 @@
 import { execSync } from 'child_process';
 import fs from 'fs';
 
+try {
+  const currentBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
+  if (currentBranch !== 'main') {
+    console.error(
+      `Error: You must be on the 'main' branch to create a release. Current branch: ${currentBranch}`
+    );
+    process.exit(1);
+  }
+} catch (error) {
+  console.error('Failed to determine current git branch:', error.message);
+  process.exit(1);
+}
+
+try {
+  const changes = execSync('git status --porcelain').toString();
+  if (changes.length > 0) {
+    console.error(
+      'Error: You have uncommitted changes. Please commit or stash them before creating a release.'
+    );
+    console.error(changes);
+    process.exit(1);
+  }
+} catch (error) {
+  console.error('Failed to check git status:', error.message);
+  process.exit(1);
+}
+
 const args = process.argv.slice(2);
 const releaseType = args[0] || 'patch';
 
@@ -40,4 +67,3 @@ execSync(`gh release create v${version} --title 'v${version}' --notes 'Version $
 });
 
 console.log(`Release v${version} created successfully!`);
-// GitHub Actions workflow will handle the npm publish automatically

package/index.mjs

@@ -21,8 +21,8 @@ async function main() {
       process.exit(0);
     }
 
-    if (args.testLogin) {
-      logger.info('Testing login...');
+    if (args.verifyLogin) {
+      logger.info('Verifying login...');
       const result = await authManager.testLogin();
       console.log(JSON.stringify(result));
       process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Microsoft 365 MCP Server",
   "type": "module",
   "main": "index.mjs",
@@ -12,7 +12,10 @@
     "test:watch": "vitest",
     "start": "node index.mjs",
     "format": "prettier --write \"**/*.{js,mjs,json,md}\"",
-    "release": "node bin/release.mjs"
+    "release": "node bin/release.mjs",
+    "download-openapi": "node bin/download-openapi.mjs",
+    "inspect": "npx @modelcontextprotocol/inspector node index.mjs",
+    "postinstall": "npm run download-openapi"
   },
   "keywords": [
     "microsoft",
@@ -29,6 +32,7 @@
     "@azure/msal-node": "^2.1.0",
     "@modelcontextprotocol/sdk": "^1.8.0",
     "commander": "^11.1.0",
+    "js-yaml": "^4.1.0",
     "keytar": "^7.9.0",
     "winston": "^3.17.0",
     "zod": "^3.24.2"

package/src/auth-tools.mjs

@@ -1,28 +1,53 @@
+import { z } from 'zod';
+
 export function registerAuthTools(server, authManager) {
-  server.tool('login', {}, async () => {
-    try {
-      const text = await new Promise((r) => {
-        authManager.acquireTokenByDeviceCode(r);
-      });
-      return {
-        content: [
-          {
-            type: 'text',
-            text,
-          },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: JSON.stringify({ error: `Authentication failed: ${error.message}` }),
-          },
-        ],
-      };
+  server.tool(
+    'login',
+    {
+      force: z.boolean().default(false).describe('Force a new login even if already logged in'),
+    },
+    async ({ force }) => {
+      try {
+        if (!force) {
+          const loginStatus = await authManager.testLogin();
+          if (loginStatus.success) {
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: JSON.stringify({
+                    message: 'Already logged in',
+                    ...loginStatus,
+                  }),
+                },
+              ],
+            };
+          }
+        }
+
+        const text = await new Promise((r) => {
+          authManager.acquireTokenByDeviceCode(r);
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ error: `Authentication failed: ${error.message}` }),
+            },
+          ],
+        };
+      }
     }
-  });
+  );
 
   server.tool('logout', {}, async () => {
     try {
@@ -47,18 +72,6 @@ export function registerAuthTools(server, authManager) {
     }
   });
 
-  server.tool('test-login', {}, async () => {
-    const result = await authManager.testLogin();
-    return {
-      content: [
-        {
-          type: 'text',
-          text: JSON.stringify(result),
-        },
-      ],
-    };
-  });
-
   server.tool('verify-login', {}, async () => {
     const testResult = await authManager.testLogin();
 

package/src/auth.mjs

@@ -19,10 +19,7 @@ const DEFAULT_CONFIG = {
 
 const DEFAULT_SCOPES = [
   'Files.ReadWrite',
-  'Files.ReadWrite.All',
-  'Sites.ReadWrite.All',
   'User.Read',
-  'User.ReadBasic.All',
   'Calendars.Read',
   'Calendars.ReadWrite',
   'Mail.Read',
@@ -111,7 +108,7 @@ class AuthManager {
       deviceCodeCallback: (response) => {
         const text = ['\n', response.message, '\n'].join('');
         if (hack) {
-          hack(text + 'After login run the "test login" command');
+          hack(text + 'After login run the "verify login" command');
         } else {
           console.log(text);
         }

package/src/cli.mjs

@@ -17,8 +17,7 @@ program
   .option('-v', 'Enable verbose logging')
   .option('--login', 'Login using device code flow')
   .option('--logout', 'Log out and clear saved credentials')
-  .option('--test-login', 'Test login without starting the server')
-  .option('--file <path>', 'Specify Excel file path');
+  .option('--verify-login', 'Verify login without starting the server');
 
 export function parseArgs() {
   program.parse();