simply-outlook-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hmmroger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# Simply Outlook MCP Server
+
+A Model Context Protocol (MCP) server that enables AI assistants to interact with Microsoft Outlook calendars and emails through the Microsoft Graph API.
+
+## 🚀 Features
+
+### 📅 Calendar Management
+- **Get Calendar Events** - Retrieve calendar events within specified date ranges
+- **Create Calendar Events** - Create personal calendar events
+- **Create Events with Invites** - Create calendar events and send invitations to attendees
+- **Update Calendar Events** - Modify existing calendar events (subject, time, location, etc.)
+
+### 📧 Email Operations
+- **Get Messages** - Fetch recent Outlook messages with date filtering
+- **Get Message Content** - Retrieve full content of specific messages by ID
+- **Search Messages** - Search emails by keywords (sender, subject, content)
+- **Send Messages** - Send new emails to specified recipients
+- **Reply to Messages** - Reply to existing email messages
+- **Pagination Support** - Handle large result sets with skip/limit parameters
+
+### ⚙️ Configuration
+- **Selective Tool Control** - Enable/disable individual tools via environment variables
+- **Environment Configuration** - Flexible setup via environment variables
+- **TypeScript Support** - Full type definitions included
+
+## 📋 Prerequisites
+
+- [**Node.js**](https://nodejs.org/) 20.19.0 or higher
+- **Azure AD Application**:
+  - `Calendars.ReadWrite` - Read and write calendar events
+  - `Mail.Read` - Read email messages
+  - `Mail.Send` - Send email messages
+  - `User.Read` - Read user profile information
+
+## 🛠️ Installation
+
+### Using npx (Recommended)
+No installation required! Simply use `npx` to run the latest version:
+
+### Global Installation (Optional)
+If you prefer to install globally:
+
+```bash
+npm install -g simply-outlook-mcp
+```
+
+### From Source
+For development or customization:
+
+```bash
+npm install
+npm run build
+```
+
+## 🔧 Setup
+
+> [!NOTE]
+> **Security Best Practice**: We recommend creating your own Azure AD application rather than using a client ID from an unknown 3rd party or untrusted publisher.
+>
+> This MCP server runs locally. The code that uses the Microsoft Graph access tokens stays on your machine. The Azure AD / Entra "client ID" you supply only tells the directory *which* app registration to issue tokens for. If you reuse an arbitrary or third‑party client ID, you do **not** automatically leak your tokens to that party, but you *are* accepting several avoidable risks tied to the *app registration* that they control.
+>
+> **What a third party CAN change later if you use their client ID:**
+> - Display name / branding you see during future consent prompts (could lower your guard)
+> - The set of requested delegated scopes (you may click "Accept" again out of habit)
+> - Publisher domain / verification state (influences user trust signals)
+> - Authentication settings (enabling flows they host to phish you for tokens)
+>
+
+### 1. Azure AD Application Registration
+
+1. Go to the [Azure Portal](https://portal.azure.com/)
+2. Navigate to **Microsoft Entra ID** > **Manage** > **App registrations**
+3. Click **New registration**
+4. Configure:
+   - **Name**: (Any name you like, will show up in the consent dialog)
+   - **Supported account types**: `Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)`
+   - **Redirect URI**: Leave blank
+5. After creation, in the application resource view, note down client ID in the **Overview** page:
+   - **Application (client) ID**
+6. In the application resource view, go to **Manage** > **Authentication** page:
+   - Toggle `Enable the following mobile and desktop flows` to `Yes`
+
+> [!NOTE]
+> The scopes currently requested by this MCP are designed to work with personal Microsoft account (MSA).
+
+### 2. Authentication Setup
+
+```bash
+npx simply-outlook-mcp --auth --client_id YOUR_CLIENT_ID
+```
+
+This will open a browser for device authentication. Sign in with your Microsoft account that has access to the Outlook data you want to manage.
+
+## 🚀 Usage
+
+### Using with MCP Clients
+
+The server implements the Model Context Protocol and can be used with any MCP-compatible AI assistant.
+
+### Example configuration for Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "simply-outlook-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "simply-outlook-mcp"
+      ],
+      "env": {
+        "SIMPLY_OUTLOOK_MCP_CLIENT_ID": "your-client-id",
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+```json
+{
+  "servers": {
+    "simply-outlook-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "simply-outlook-mcp"
+      ],
+      "env": {
+        "SIMPLY_OUTLOOK_MCP_CLIENT_ID": "your-client-id"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+The following environment variables can be used to configure the MCP server:
+
+### Required Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `SIMPLY_OUTLOOK_MCP_CLIENT_ID` | Azure AD Application (client) ID | `12345678-1234-1234-1234-123456789012` |
+
+### Optional Variables
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `SIMPLY_OUTLOOK_MCP_TENANT_ID` | Ignore this, for advance usage if you create single tenant or MSA only app | `common` | |
+| `SIMPLY_OUTLOOK_MCP_DISABLED_TOOLS` | Comma-separated list of tools to disable | None | `get-calendar-events,send-outlook-message` |
+
+### Tool Names for Disabling
+
+You can disable specific tools by adding their names to the `SIMPLY_OUTLOOK_MCP_DISABLED_TOOLS` environment variable:
+
+**Calendar Tools:**
+- `get-calendar-events` - Retrieve calendar events
+- `create-calendar-event` - Create personal calendar events  
+- `create-calendar-event-with-invite` - Create events with invitations
+- `update-calendar-event` - Modify existing calendar events
+
+**Email Tools:**
+- `get-outlook-messages` - Fetch recent messages
+- `get-outlook-message-content` - Get full message content
+- `search-outlook-messages` - Search emails by keywords
+- `send-outlook-message` - Send new emails
+- `reply-outlook-message` - Reply to existing emails
+
+### Example Configuration
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "simply-outlook-mcp"
+      ],
+      "env": {
+        "SIMPLY_OUTLOOK_MCP_CLIENT_ID": "12345678-1234-1234-1234-123456789012",
+        "SIMPLY_OUTLOOK_MCP_DISABLED_TOOLS": "create-calendar-event-with-invite,update-calendar-event,send-outlook-message,reply-outlook-message"
+      }
+    }
+  }
+}
+```
+
+> [!TIP]
+> **Disabling Tools**: You can disable tools you don't need for security or functionality reasons. For example, disable email sending tools (`send-outlook-message,reply-outlook-message`) if you only want read-only email access.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- GitHub Issues: [Report bugs or request features](https://github.com/hmmroger/simply-outlook-mcp/issues)
+- Repository: [https://github.com/hmmroger/simply-outlook-mcp](https://github.com/hmmroger/simply-outlook-mcp)

package/dist/auth-utils.d.ts

@@ -0,0 +1,3 @@
+import { DeviceCodeCredential, DeviceCodePromptCallback } from "@azure/identity";
+export declare const authenticate: (clientId: string, scopes: string[], tenantId?: string, isForce?: boolean) => Promise<void>;
+export declare const getDeviceCredential: (clientId: string, tenantId?: string, isForce?: boolean, promptCallback?: DeviceCodePromptCallback) => DeviceCodeCredential;

package/dist/auth-utils.js

@@ -0,0 +1,64 @@
+import fs from "fs";
+import { DeviceCodeCredential, useIdentityPlugin } from "@azure/identity";
+import { cachePersistencePlugin } from "@azure/identity-cache-persistence";
+import EventEmitter, { once } from "events";
+useIdentityPlugin(cachePersistencePlugin);
+const AUTH_RECORD_FILE = ".simply-outlook-mcp";
+export const authenticate = async (clientId, scopes, tenantId, isForce) => {
+    const deviceCodeEvent = new EventEmitter();
+    const deviceCodeCred = getDeviceCredential(clientId, tenantId, isForce, (info) => {
+        deviceCodeEvent.emit("code", info);
+    });
+    try {
+        await deviceCodeCred.getToken(scopes);
+        const authRecord = getAuthRecord();
+        console.error(`Authenticated as ${authRecord?.username}`);
+        return;
+    }
+    catch (error) {
+        // no op
+    }
+    const authPromise = deviceCodeCred.authenticate(scopes);
+    const [code] = await once(deviceCodeEvent, "code");
+    const deviceCodeInfo = code;
+    console.error(deviceCodeInfo.message);
+    const newAuthRecord = await authPromise;
+    if (!newAuthRecord) {
+        throw new Error("Authentication failed.");
+    }
+    fs.writeFileSync(getAuthRecordFile(), JSON.stringify(newAuthRecord));
+    console.error(`Authenticated as ${newAuthRecord.username}`);
+};
+export const getDeviceCredential = (clientId, tenantId, isForce, promptCallback) => {
+    const authRecord = isForce ? undefined : getAuthRecord();
+    const deviceCodeCred = new DeviceCodeCredential({
+        clientId,
+        tenantId: tenantId || "common",
+        userPromptCallback: promptCallback,
+        tokenCachePersistenceOptions: { enabled: true, name: "simply-outlook-mcp" },
+        authenticationRecord: authRecord,
+        disableAutomaticAuthentication: true,
+    });
+    return deviceCodeCred;
+};
+const getUserDataFolder = () => {
+    const folder = process.env.APPDATA?.replace?.(/(.Roaming)*$/, "\\Local") ?? process.env.HOME;
+    if (!folder) {
+        throw new Error("User data folder not defined.");
+    }
+    return folder;
+};
+const getAuthRecordFile = () => {
+    return `${getUserDataFolder()}/${AUTH_RECORD_FILE}`;
+};
+const getAuthRecord = () => {
+    try {
+        const authRecJson = fs.readFileSync(getAuthRecordFile(), { encoding: "utf8" });
+        return JSON.parse(authRecJson);
+    }
+    catch (_error) {
+        console.error("Auth record not available.");
+    }
+    return undefined;
+};
+//# sourceMappingURL=auth-utils.js.map

package/dist/common/console-logger.d.ts

@@ -0,0 +1,11 @@
+import { ILogger } from "./logger.types.js";
+export declare class ConsoleLogger implements ILogger {
+    private readonly useErrorOutput?;
+    private moduleName;
+    constructor(moduleName?: string, useErrorOutput?: boolean | undefined);
+    debug(message: string): void;
+    info(message: string): void;
+    warning(message: string): void;
+    error(message: string, error?: unknown): void;
+    createLogger(name: string): ILogger;
+}

package/dist/common/console-logger.js

@@ -0,0 +1,32 @@
+export class ConsoleLogger {
+    useErrorOutput;
+    moduleName;
+    constructor(moduleName, useErrorOutput) {
+        this.useErrorOutput = useErrorOutput;
+        this.moduleName = moduleName || "";
+    }
+    debug(message) {
+        if (process.env.NODE_ENV !== "production") {
+            const timestamp = new Date().toISOString();
+            const output = `[DEBUG] [${timestamp}]: ${message}`;
+            this.useErrorOutput ? console.error(output) : console.log(output);
+        }
+    }
+    info(message) {
+        const timestamp = new Date().toISOString();
+        const output = `[INFO] [${timestamp}]: ${this.moduleName ? this.moduleName + ": " : ""}${message}`;
+        this.useErrorOutput ? console.error(output) : console.log(output);
+    }
+    warning(message) {
+        const timestamp = new Date().toISOString();
+        console.warn(`[WARNING] [${timestamp}]: ${this.moduleName ? this.moduleName + ": " : ""}${message}`);
+    }
+    error(message, error) {
+        const timestamp = new Date().toISOString();
+        console.error(`[ERROR] [${timestamp}]: ${this.moduleName ? this.moduleName + ": " : ""}${message}`, error);
+    }
+    createLogger(name) {
+        return new ConsoleLogger(name, this.useErrorOutput);
+    }
+}
+//# sourceMappingURL=console-logger.js.map

package/dist/common/logger.types.d.ts

@@ -0,0 +1,7 @@
+export interface ILogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warning(message: string): void;
+    error(message: string, error?: unknown): void;
+    createLogger(name: string): ILogger;
+}

package/dist/common/logger.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logger.types.js.map

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { config } from "dotenv";
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer, SIMPLY_OUTLOOK_MCP_SCOPES } from "./simply-outlook-mcp.js";
+import { SimplyOutlookMcpEnvs } from "./simply-outlook-mcp.types.js";
+import { authenticate, getDeviceCredential } from "./auth-utils.js";
+config({ quiet: true });
+const main = async () => {
+    const argv = yargs(hideBin(process.argv))
+        .option("auth", {
+        type: "boolean",
+        description: "Initialize and save authentication record.",
+    })
+        .option("force", {
+        type: "boolean",
+        description: "Re-initialize authentication to switch account.",
+        implies: ["auth"],
+    })
+        .option("client_id", {
+        type: "string",
+        description: "Application ID created in Azure portal.",
+    })
+        .option("tenant_id", {
+        type: "string",
+        description: "Application's tenant ID.",
+    })
+        .parseSync();
+    const clientId = argv.client_id || process.env[SimplyOutlookMcpEnvs.SIMPLY_OUTLOOK_MCP_CLIENT_ID];
+    if (!clientId) {
+        throw new Error("Missing client ID.");
+    }
+    const tenantId = argv.tenant_id || process.env[SimplyOutlookMcpEnvs.SIMPLY_OUTLOOK_MCP_TENANT_ID];
+    if (argv.auth) {
+        await authenticate(clientId, SIMPLY_OUTLOOK_MCP_SCOPES, tenantId, argv.force);
+        return;
+    }
+    const credential = getDeviceCredential(clientId, tenantId, argv.force);
+    const server = await createMcpServer(credential);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Simply Outlook MCP Server running on stdio.");
+};
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/simply-outlook/graph-service.d.ts

@@ -0,0 +1,30 @@
+import { TokenCredential } from "@azure/identity";
+import { ILogger } from "../common/logger.types.js";
+import { CalendarEventData, DateTimeRange, MailMessageData } from "./graph-service.types.js";
+export declare class GraphService {
+    private readonly logger;
+    private readonly tokenCredential;
+    private readonly scopes;
+    private graphClient;
+    private domPurify;
+    private nhm;
+    private marked;
+    private mailFolders;
+    private filterFolderIds;
+    constructor(logger: ILogger, tokenCredential: TokenCredential, scopes: string[]);
+    isAuthenticated(): Promise<boolean>;
+    getCalendarEvents(startDateTimeRange?: DateTimeRange, limit?: number, skip?: number): Promise<CalendarEventData[]>;
+    createCalendarEvent(subject: string, content: string, utcStartDate: string, utcEndDate: string, userEmails?: string[], location?: string, isMeeting?: boolean): Promise<CalendarEventData>;
+    updateCalendarEvent(id: string, content?: string, subject?: string, utcStartDate?: string, utcEndDate?: string, location?: string): Promise<CalendarEventData>;
+    getOutlookMessages(receivedDateTimeRange?: DateTimeRange, searchQuery?: string, limit?: number, skip?: number): Promise<MailMessageData[]>;
+    getOutlookMessageById(id: string): Promise<MailMessageData>;
+    sendOutlookMessage(subject: string, content: string, recipientEmails: string[]): Promise<void>;
+    replyOutlookMessage(replyMessageId: string, content: string): Promise<void>;
+    private getMailFolders;
+    private getFilterFolderIds;
+    private parseHtmlToMarkdown;
+    private parseMarkdownToHtml;
+    private isCalendarEventData;
+    private isMailMessageData;
+    private isMailFolderData;
+}