npm - outlook-cli - Versions diffs - 1.2.0 - Mend

outlook-cli 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/CLI.md +89 -0
package/LICENSE +21 -0
package/QUICKSTART.md +104 -0
package/README.md +994 -0
package/auth/index.js +36 -0
package/auth/oauth-server.js +139 -0
package/auth/token-manager.js +199 -0
package/auth/token-storage.js +282 -0
package/auth/tools.js +127 -0
package/calendar/accept.js +64 -0
package/calendar/cancel.js +64 -0
package/calendar/create.js +69 -0
package/calendar/decline.js +64 -0
package/calendar/delete.js +59 -0
package/calendar/index.js +123 -0
package/calendar/list.js +77 -0
package/cli.js +1349 -0
package/config.js +84 -0
package/docs/PROJECT-STRUCTURE.md +52 -0
package/docs/PUBLISHING.md +86 -0
package/docs/REFERENCE.md +679 -0
package/email/folder-utils.js +171 -0
package/email/index.js +157 -0
package/email/list.js +89 -0
package/email/mark-as-read.js +101 -0
package/email/read.js +128 -0
package/email/search.js +282 -0
package/email/send.js +120 -0
package/folder/create.js +124 -0
package/folder/index.js +78 -0
package/folder/list.js +264 -0
package/folder/move.js +163 -0
package/index.js +136 -0
package/outlook-auth-server.js +305 -0
package/package.json +76 -0
package/rules/create.js +248 -0
package/rules/index.js +177 -0
package/rules/list.js +202 -0
package/tool-registry.js +54 -0
package/utils/graph-api.js +120 -0
package/utils/mock-data.js +145 -0
package/utils/odata-helpers.js +40 -0

package/auth/index.js ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * Authentication module for Outlook MCP server
+ */
+const tokenManager = require('./token-manager');
+const { authTools } = require('./tools');
+/**
+ * Ensures the user is authenticated and returns an access token
+ * @param {boolean} forceNew - Whether to force a new authentication
+ * @returns {Promise<string>} - Access token
+ * @throws {Error} - If authentication fails
+ */
+async function ensureAuthenticated(forceNew = false) {
+  if (forceNew) {
+    // Force re-authentication
+    throw new Error('Authentication required');
+  }
+  // Check for existing token and try refresh flow when needed.
+  let accessToken = tokenManager.getAccessToken();
+  if (!accessToken) {
+    accessToken = await tokenManager.getValidAccessToken();
+  }
+  if (!accessToken) {
+    throw new Error('Authentication required');
+  }
+  return accessToken;
+}
+module.exports = {
+  tokenManager,
+  authTools,
+  ensureAuthenticated
+};

package/auth/oauth-server.js ADDED Viewed

@@ -0,0 +1,139 @@
+const querystring = require('querystring');
+const https = require('https');
+const crypto = require('crypto');
+const TokenStorage = require('./token-storage');
+// HTML templates
+function escapeHtml(unsafe) {
+  return unsafe
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+const templates = {
+  authError: (error, errorDescription) => `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1 style="color: #e74c3c;">❌ Authorization Failed</h1>
+        <p><strong>Error:</strong> ${escapeHtml(error)}</p>
+        ${errorDescription ? `<p><strong>Description:</strong> ${escapeHtml(errorDescription)}</p>` : ''}
+        <p>You can close this window and try again.</p>
+      </body>
+    </html>`,
+  authSuccess: `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1 style="color: #2ecc71;">✅ Authentication Successful</h1>
+        <p>You have successfully authenticated with Microsoft Graph API.</p>
+        <p>You can close this window.</p>
+      </body>
+    </html>`,
+  tokenExchangeError: (error) => `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1 style="color: #e74c3c;">❌ Token Exchange Failed</h1>
+        <p>Failed to exchange authorization code for access token.</p>
+        <p><strong>Error:</strong> ${escapeHtml(error instanceof Error ? error.message : String(error))}</p>
+        <p>You can close this window and try again.</p>
+      </body>
+    </html>`,
+  tokenStatus: (status) => `
+    <html>
+      <body style="font-family: Arial, sans-serif; text-align: center; margin-top: 50px;">
+        <h1>🔐 Token Status</h1>
+        <p>${escapeHtml(status)}</p>
+      </body>
+    </html>`
+};
+function createAuthConfig(envPrefix = 'MS_') {
+  return {
+    clientId: process.env[`${envPrefix}CLIENT_ID`] || '',
+    clientSecret: process.env[`${envPrefix}CLIENT_SECRET`] || '',
+    redirectUri: process.env[`${envPrefix}REDIRECT_URI`] || 'http://localhost:3333/auth/callback',
+    scopes: (process.env[`${envPrefix}SCOPES`] || 'offline_access User.Read Mail.Read').split(' '),
+    tokenEndpoint: process.env[`${envPrefix}TOKEN_ENDPOINT`] || 'https://login.microsoftonline.com/consumers/oauth2/v2.0/token',
+    authEndpoint: process.env[`${envPrefix}AUTH_ENDPOINT`] || 'https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize'
+  };
+}
+function setupOAuthRoutes(app, tokenStorage, authConfig, envPrefix = 'MS_') {
+  if (!authConfig) {
+    authConfig = createAuthConfig(envPrefix);
+  }
+  if (!(tokenStorage instanceof TokenStorage)) {
+    if (process.env.NODE_ENV !== 'test') {
+      console.error("Error: tokenStorage is not an instance of TokenStorage. OAuth routes will not function correctly.");
+    }
+  }
+  app.get('/auth', (req, res) => {
+    if (!authConfig.clientId) {
+      return res.status(500).send(templates.authError('Configuration Error', 'Client ID is not configured.'));
+    }
+    const state = crypto.randomBytes(16).toString('hex');
+    const authorizationUrl = `${authConfig.authEndpoint}?` +
+      querystring.stringify({
+        client_id: authConfig.clientId,
+        response_type: 'code',
+        redirect_uri: authConfig.redirectUri,
+        scope: authConfig.scopes.join(' '),
+        response_mode: 'query',
+        state: state
+      });
+    res.redirect(authorizationUrl);
+  });
+  app.get('/auth/callback', async (req, res) => {
+    const { code, error, error_description, state } = req.query;
+    // Require a state value to reduce CSRF risk. The integrating app should also
+    // validate state value matching using a session or short-lived server store.
+    if (!state) {
+        console.error("OAuth callback received without a 'state' parameter. Rejecting request to prevent potential CSRF attack.");
+        return res.status(400).send(templates.authError('Missing State Parameter', 'The state parameter was missing from the OAuth callback. This is a security risk. Please try authenticating again.'));
+    }
+    if (error) {
+      return res.status(400).send(templates.authError(error, error_description));
+    }
+    if (!code) {
+      return res.status(400).send(templates.authError('Missing Authorization Code', 'No authorization code was provided in the callback.'));
+    }
+    try {
+      await tokenStorage.exchangeCodeForTokens(code);
+      res.send(templates.authSuccess);
+    } catch (exchangeError) {
+      console.error('Token exchange error:', exchangeError);
+      res.status(500).send(templates.tokenExchangeError(exchangeError));
+    }
+  });
+  app.get('/token-status', async (req, res) => {
+    try {
+      const token = await tokenStorage.getValidAccessToken();
+      if (token) {
+        const expiryDate = new Date(tokenStorage.getExpiryTime());
+        res.send(templates.tokenStatus(`Access token is valid. Expires at: ${expiryDate.toLocaleString()}`));
+      } else {
+        res.send(templates.tokenStatus('No valid access token found. Please authenticate.'));
+      }
+    } catch (err) {
+      res.status(500).send(templates.tokenStatus(`Error checking token status: ${err.message}`));
+    }
+  });
+}
+module.exports = {
+  setupOAuthRoutes,
+  createAuthConfig
+};

package/auth/token-manager.js ADDED Viewed

@@ -0,0 +1,199 @@
+/**
+ * Token management for Microsoft Graph API authentication
+ */
+const fs = require('fs');
+const config = require('../config');
+const TokenStorage = require('./token-storage');
+// Global variable to store tokens
+let cachedTokens = null;
+let tokenStorage = null;
+const TOKEN_EXPIRY_BUFFER_MS = 60 * 1000;
+function debugLog(message) {
+  if (config.DEBUG_LOGS) {
+    console.error(`[TOKEN-MANAGER] ${message}`);
+  }
+}
+function isTokenUsable(tokens) {
+  if (!tokens || !tokens.access_token) {
+    return false;
+  }
+  if (!tokens.expires_at) {
+    // Some token responses may not include expires_at. Accept for backward compatibility.
+    return true;
+  }
+  const expiry = Number(tokens.expires_at);
+  if (!Number.isFinite(expiry)) {
+    return false;
+  }
+  return Date.now() < (expiry - TOKEN_EXPIRY_BUFFER_MS);
+}
+function getTokenStorage() {
+  if (!tokenStorage) {
+    tokenStorage = new TokenStorage({
+      tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+      clientId: config.AUTH_CONFIG.clientId,
+      clientSecret: config.AUTH_CONFIG.clientSecret,
+      redirectUri: config.AUTH_CONFIG.redirectUri,
+      scopes: config.AUTH_CONFIG.scopes,
+      tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint
+    });
+  }
+  return tokenStorage;
+}
+/**
+ * Loads authentication tokens from the token file
+ * @returns {object|null} - The loaded tokens or null if not available
+ */
+function loadTokenCache() {
+  try {
+    const tokenPath = config.AUTH_CONFIG.tokenStorePath;
+    debugLog(`Attempting to load tokens from ${tokenPath}`);
+    if (!fs.existsSync(tokenPath)) {
+      debugLog('Token file does not exist');
+      cachedTokens = null;
+      return null;
+    }
+    const tokenData = fs.readFileSync(tokenPath, 'utf8');
+    try {
+      const tokens = JSON.parse(tokenData);
+      if (!isTokenUsable(tokens)) {
+        debugLog('Token cache exists but is unusable or expired');
+        cachedTokens = null;
+        return null;
+      }
+      cachedTokens = tokens;
+      return tokens;
+    } catch (parseError) {
+      console.error('Error parsing token cache JSON:', parseError.message);
+      cachedTokens = null;
+      return null;
+    }
+  } catch (error) {
+    console.error('Error loading token cache:', error.message);
+    cachedTokens = null;
+    return null;
+  }
+}
+/**
+ * Saves authentication tokens to the token file
+ * @param {object} tokens - The tokens to save
+ * @returns {boolean} - Whether the save was successful
+ */
+function saveTokenCache(tokens) {
+  try {
+    const tokenPath = config.AUTH_CONFIG.tokenStorePath;
+    fs.writeFileSync(tokenPath, JSON.stringify(tokens, null, 2));
+    cachedTokens = tokens;
+    if (tokenStorage) {
+      tokenStorage.tokens = tokens;
+    }
+    return true;
+  } catch (error) {
+    console.error('Error saving token cache:', error.message);
+    return false;
+  }
+}
+/**
+ * Gets the current access token, loading from cache if necessary
+ * @returns {string|null} - The access token or null if not available
+ */
+function getAccessToken() {
+  if (isTokenUsable(cachedTokens)) {
+    return cachedTokens.access_token;
+  }
+  const tokens = loadTokenCache();
+  return tokens ? tokens.access_token : null;
+}
+/**
+ * Gets a valid access token and attempts refresh when possible.
+ * @returns {Promise<string|null>} - Valid access token or null
+ */
+async function getValidAccessToken() {
+  const directToken = getAccessToken();
+  if (directToken) {
+    return directToken;
+  }
+  try {
+    const storage = getTokenStorage();
+    const refreshedToken = await storage.getValidAccessToken();
+    if (refreshedToken && storage.tokens) {
+      cachedTokens = storage.tokens;
+    }
+    return refreshedToken || null;
+  } catch (error) {
+    debugLog(`Unable to get valid access token via refresh flow: ${error.message}`);
+    return null;
+  }
+}
+/**
+ * Creates a test access token for use in test mode
+ * @returns {object} - The test tokens
+ */
+function createTestTokens() {
+  const testTokens = {
+    access_token: "test_access_token_" + Date.now(),
+    refresh_token: "test_refresh_token_" + Date.now(),
+    expires_at: Date.now() + (3600 * 1000) // 1 hour
+  };
+  saveTokenCache(testTokens);
+  return testTokens;
+}
+/**
+ * Clears in-memory and on-disk token cache.
+ */
+function clearTokenCache() {
+  cachedTokens = null;
+  if (tokenStorage) {
+    tokenStorage.tokens = null;
+  }
+  try {
+    const tokenPath = config.AUTH_CONFIG.tokenStorePath;
+    if (fs.existsSync(tokenPath)) {
+      fs.unlinkSync(tokenPath);
+    }
+    return true;
+  } catch (error) {
+    console.error(`Failed to clear token cache: ${error.message}`);
+    return false;
+  }
+}
+module.exports = {
+  loadTokenCache,
+  saveTokenCache,
+  getAccessToken,
+  getValidAccessToken,
+  createTestTokens,
+  clearTokenCache
+};

package/auth/token-storage.js ADDED Viewed

@@ -0,0 +1,282 @@
+const fs = require('fs').promises;
+const path = require('path');
+const https = require('https');
+const querystring = require('querystring');
+class TokenStorage {
+  constructor(config) {
+    this.config = {
+      tokenStorePath: path.join(process.env.HOME || process.env.USERPROFILE, '.outlook-mcp-tokens.json'),
+      clientId: process.env.OUTLOOK_CLIENT_ID || process.env.MS_CLIENT_ID,
+      clientSecret: process.env.OUTLOOK_CLIENT_SECRET || process.env.MS_CLIENT_SECRET,
+      redirectUri: process.env.OUTLOOK_REDIRECT_URI || process.env.MS_REDIRECT_URI || 'http://localhost:3333/auth/callback',
+      scopes: (process.env.OUTLOOK_SCOPES || process.env.MS_SCOPES || 'offline_access User.Read Mail.Read').split(' '),
+      tokenEndpoint: process.env.OUTLOOK_TOKEN_ENDPOINT || process.env.MS_TOKEN_ENDPOINT || 'https://login.microsoftonline.com/consumers/oauth2/v2.0/token',
+      refreshTokenBuffer: 5 * 60 * 1000, // 5 minutes buffer for token refresh
+      debug: process.env.OUTLOOK_DEBUG === 'true' || process.env.MCP_DEBUG === 'true',
+      ...config // Allow overriding default config
+    };
+    this.tokens = null;
+    this._loadPromise = null;
+    this._refreshPromise = null;
+    if (!this.config.clientId || !this.config.clientSecret) {
+      console.warn("TokenStorage: client ID/secret is not configured. Set OUTLOOK_CLIENT_ID/OUTLOOK_CLIENT_SECRET or MS_CLIENT_ID/MS_CLIENT_SECRET.");
+    }
+  }
+  _debugLog(...args) {
+    if (this.config.debug) {
+      console.error('[TokenStorage]', ...args);
+    }
+  }
+  async _loadTokensFromFile() {
+    try {
+      const tokenData = await fs.readFile(this.config.tokenStorePath, 'utf8');
+      this.tokens = JSON.parse(tokenData);
+      this._debugLog('Tokens loaded from file.');
+      return this.tokens;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this._debugLog('Token file not found. No tokens loaded.');
+      } else {
+        this._debugLog('Error loading token cache:', error.message);
+      }
+      this.tokens = null;
+      return null;
+    }
+  }
+  async _saveTokensToFile() {
+    if (!this.tokens) {
+      this._debugLog('No tokens to save.');
+      return false;
+    }
+    try {
+      await fs.writeFile(this.config.tokenStorePath, JSON.stringify(this.tokens, null, 2));
+      this._debugLog('Tokens saved successfully.');
+      // return true; // No longer returning boolean, will throw on error.
+    } catch (error) {
+      this._debugLog('Error saving token cache:', error.message);
+      throw error; // Propagate the error
+    }
+  }
+  async getTokens() {
+    if (this.tokens) {
+      return this.tokens;
+    }
+    if (!this._loadPromise) {
+        this._loadPromise = this._loadTokensFromFile().finally(() => {
+            this._loadPromise = null; // Reset promise once completed
+        });
+    }
+    return this._loadPromise;
+  }
+  getExpiryTime() {
+    return this.tokens && this.tokens.expires_at ? this.tokens.expires_at : 0;
+  }
+  isTokenExpired() {
+    if (!this.tokens || !this.tokens.expires_at) {
+      return true; // No token or no expiry means it's effectively expired or invalid
+    }
+    // Check if current time is past expiry time, considering a buffer
+    return Date.now() >= (this.tokens.expires_at - this.config.refreshTokenBuffer);
+  }
+  async getValidAccessToken() {
+    await this.getTokens(); // Ensure tokens are loaded
+    if (!this.tokens || !this.tokens.access_token) {
+      this._debugLog('No access token available.');
+      return null;
+    }
+    if (this.isTokenExpired()) {
+      this._debugLog('Access token expired or nearing expiration. Attempting refresh.');
+      if (this.tokens.refresh_token) {
+        try {
+          return await this.refreshAccessToken();
+        } catch (refreshError) {
+          this._debugLog('Failed to refresh access token:', refreshError.message);
+          this.tokens = null; // Invalidate tokens on refresh failure
+          await this._saveTokensToFile(); // Persist invalidation
+          return null;
+        }
+      } else {
+        console.warn('No refresh token available. Cannot refresh access token.');
+        this.tokens = null; // Invalidate tokens as they are expired and cannot be refreshed
+        await this._saveTokensToFile(); // Persist invalidation
+        return null;
+      }
+    }
+    return this.tokens.access_token;
+  }
+  async refreshAccessToken() {
+    if (!this.tokens || !this.tokens.refresh_token) {
+      throw new Error('No refresh token available to refresh the access token.');
+    }
+    // Prevent multiple concurrent refresh attempts
+    if (this._refreshPromise) {
+      this._debugLog("Refresh already in progress, returning existing promise.");
+        return this._refreshPromise.then(tokens => tokens.access_token);
+    }
+    this._debugLog('Attempting to refresh access token...');
+    const postData = querystring.stringify({
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+      grant_type: 'refresh_token',
+      refresh_token: this.tokens.refresh_token,
+      scope: this.config.scopes.join(' ')
+    });
+    const requestOptions = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(postData)
+      }
+    };
+    this._refreshPromise = new Promise((resolve, reject) => {
+        const req = https.request(this.config.tokenEndpoint, requestOptions, (res) => {
+            let data = '';
+            res.on('data', (chunk) => data += chunk);
+            res.on('end', async () => {
+                try {
+                    const responseBody = JSON.parse(data);
+                    if (res.statusCode >= 200 && res.statusCode < 300) {
+                        this.tokens.access_token = responseBody.access_token;
+                        // Microsoft Graph API refresh tokens may or may not return a new refresh_token
+                        if (responseBody.refresh_token) {
+                            this.tokens.refresh_token = responseBody.refresh_token;
+                        }
+                        this.tokens.expires_in = responseBody.expires_in;
+                        this.tokens.expires_at = Date.now() + (responseBody.expires_in * 1000);
+                        try {
+                            await this._saveTokensToFile();
+                            this._debugLog('Access token refreshed and saved successfully.');
+                            resolve(this.tokens);
+                        } catch (saveError) {
+                            this._debugLog('Failed to save refreshed tokens:', saveError.message);
+                            // Even if save fails, tokens are updated in memory.
+                            // Depending on desired strictness, could reject here.
+                            // For now, resolve with in-memory tokens but log critical error.
+                            // Or, to be stricter and align with re-throwing:
+                            reject(new Error(`Access token refreshed but failed to save: ${saveError.message}`));
+                        }
+                    } else {
+                      this._debugLog('Error refreshing token response:', responseBody);
+                        reject(new Error(responseBody.error_description || `Token refresh failed with status ${res.statusCode}`));
+                    }
+                } catch (e) { // Catch any error during parsing or saving
+                    this._debugLog('Error processing refresh token response or saving tokens:', e.message);
+                    reject(e);
+                } finally {
+                    this._refreshPromise = null; // Clear promise after completion
+                }
+            });
+        });
+        req.on('error', (error) => {
+                this._debugLog('HTTP error during token refresh:', error.message);
+            reject(error);
+            this._refreshPromise = null; // Clear promise on error
+        });
+        req.write(postData);
+        req.end();
+    });
+    return this._refreshPromise.then(tokens => tokens.access_token);
+  }
+  async exchangeCodeForTokens(authCode) {
+    if (!this.config.clientId || !this.config.clientSecret) {
+        throw new Error("Client ID or Client Secret is not configured. Cannot exchange code for tokens.");
+    }
+    this._debugLog('Exchanging authorization code for tokens...');
+    const postData = querystring.stringify({
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+      grant_type: 'authorization_code',
+      code: authCode,
+      redirect_uri: this.config.redirectUri,
+      scope: this.config.scopes.join(' ')
+    });
+    const requestOptions = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(postData)
+      }
+    };
+    return new Promise((resolve, reject) => {
+      const req = https.request(this.config.tokenEndpoint, requestOptions, (res) => {
+        let data = '';
+        res.on('data', (chunk) => data += chunk);
+        res.on('end', async () => {
+          try {
+            const responseBody = JSON.parse(data);
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              this.tokens = {
+                access_token: responseBody.access_token,
+                refresh_token: responseBody.refresh_token,
+                expires_in: responseBody.expires_in,
+                expires_at: Date.now() + (responseBody.expires_in * 1000),
+                scope: responseBody.scope,
+                token_type: responseBody.token_type
+              };
+              try {
+                await this._saveTokensToFile();
+                this._debugLog('Tokens exchanged and saved successfully.');
+                resolve(this.tokens);
+              } catch (saveError) {
+                this._debugLog('Failed to save exchanged tokens:', saveError.message);
+                // Similar to refresh, tokens are in memory but not persisted.
+                // Rejecting to indicate the operation wasn't fully successful.
+                reject(new Error(`Tokens exchanged but failed to save: ${saveError.message}`));
+              }
+            } else {
+              this._debugLog('Error exchanging code for tokens response:', responseBody);
+              reject(new Error(responseBody.error_description || `Token exchange failed with status ${res.statusCode}`));
+            }
+          } catch (e) { // Catch any error during parsing or saving
+            this._debugLog('Error processing token exchange response:', e.message);
+            reject(new Error(`Error processing token response: ${e.message}. Response data: ${data}`));
+          }
+        });
+      });
+      req.on('error', (error) => {
+        this._debugLog('HTTP error during code exchange:', error.message);
+        reject(error);
+      });
+      req.write(postData);
+      req.end();
+    });
+  }
+  // Utility to clear tokens, e.g., for logout or forcing re-auth
+  async clearTokens() {
+    this.tokens = null;
+    try {
+      await fs.unlink(this.config.tokenStorePath);
+      this._debugLog('Token file deleted successfully.');
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        this._debugLog('Token file not found, nothing to delete.');
+      } else {
+        this._debugLog('Error deleting token file:', error.message);
+      }
+    }
+  }
+}
+module.exports = TokenStorage;