@teamnetwork/m365-mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,199 @@
+# @teamnetwork/m365-mcp-server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Microsoft 365 Email and Calendar access, using **app-only (client credentials) authentication** — no user login flows required.
+
+Supports multiple accounts, shared mailboxes, per-mailbox read-only access control, folder navigation, and date/content filtering. Designed to be extended with Teams support later.
+
+---
+
+## Prerequisites
+
+- Node.js 18+
+- A Microsoft 365 tenant with an **Azure AD app registration** configured for app-only access (see [Admin Setup](#admin-setup) below)
+
+---
+
+## Installation
+
+```bash
+npm install -g @teamnetwork/m365-mcp-server
+```
+
+Or run directly without installing:
+
+```bash
+npx @teamnetwork/m365-mcp-server
+```
+
+---
+
+## Configuration
+
+Create a JSON config file (e.g. `m365-config.json`) based on the example below. **Keep this file secure — it contains your client secret.**
+
+```json
+{
+  "connection": {
+    "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+    "clientSecret": "your-client-secret"
+  },
+  "accounts": [
+    {
+      "id": "main",
+      "displayName": "Main Organisation",
+      "mailboxes": [
+        { "email": "user@org.com", "readonly": false },
+        { "email": "shared@org.com", "readonly": true, "displayName": "Shared (read-only)" }
+      ]
+    },
+    {
+      "id": "partner",
+      "displayName": "Partner Tenant",
+      "tenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+      "clientId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+      "clientSecret": "partner-secret",
+      "mailboxes": [
+        { "email": "partner@other.com", "readonly": false }
+      ]
+    }
+  ]
+}
+```
+
+### Config notes
+
+- The top-level `connection` block provides default credentials for all accounts.
+- Each account can override `tenantId`, `clientId`, and/or `clientSecret` individually — useful for multi-tenant setups.
+- `readonly: true` mailboxes block all write operations (send, reply, move, create/update events) at the server level.
+
+Set the path to your config via the `M365_CONFIG_PATH` environment variable:
+
+```bash
+export M365_CONFIG_PATH=/path/to/m365-config.json
+```
+
+---
+
+## Claude Desktop / Claude Code Setup
+
+Add the following to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "m365": {
+      "command": "npx",
+      "args": ["@teamnetwork/m365-mcp-server"],
+      "env": {
+        "M365_CONFIG_PATH": "/path/to/m365-config.json"
+      }
+    }
+  }
+}
+```
+
+If installed globally, you can use the `m365-mcp` command instead:
+
+```json
+{
+  "mcpServers": {
+    "m365": {
+      "command": "m365-mcp",
+      "env": {
+        "M365_CONFIG_PATH": "/path/to/m365-config.json"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available Tools
+
+### Email
+
+| Tool | Description |
+|---|---|
+| `list_mailboxes` | List configured accounts and mailboxes with read/write status |
+| `list_folders` | List mail folders (top-level or child folders) |
+| `list_messages` | List messages with optional filters: date range, subject, body keyword, sender |
+| `get_message` | Get full message details including body |
+| `send_message` | Send an email (non-readonly mailboxes only) |
+| `reply_message` | Reply or reply-all to a message (non-readonly mailboxes only) |
+| `move_message` | Move a message to another folder (non-readonly mailboxes only) |
+
+### Calendar
+
+| Tool | Description |
+|---|---|
+| `list_calendars` | List calendars for a mailbox |
+| `list_events` | List events in a date range (recurring events expanded into instances) |
+| `get_event` | Get full event details |
+| `create_event` | Create a new event (non-readonly mailboxes only) |
+| `update_event` | Update an existing event (non-readonly mailboxes only) |
+
+---
+
+## Admin Setup
+
+Before the server can access mailboxes, a tenant admin must complete the following steps.
+
+### 1. Register an Azure AD Application
+
+In the [Azure Portal](https://portal.azure.com) → **App registrations → New registration**:
+
+- Set a name (e.g. `M365 MCP Server`)
+- Note the **Application (client) ID** and **Directory (tenant) ID**
+- Under **Certificates & secrets**, create a client secret and note the value
+
+Grant the following **Application permissions** (not Delegated) and click **Grant admin consent**:
+
+| Permission | Required for |
+|---|---|
+| `Mail.Read` | Reading email |
+| `Mail.ReadWrite` | Moving messages |
+| `Mail.Send` | Sending and replying |
+| `Calendars.Read` | Reading calendar events |
+| `Calendars.ReadWrite` | Creating and updating events |
+
+### 2. Restrict Mailbox Access (Recommended)
+
+By default, the above permissions grant access to **all mailboxes** in the tenant. Use an `ApplicationAccessPolicy` in Exchange Online to restrict access to only the mailboxes in your config.
+
+Run the following in **Exchange Online PowerShell**:
+
+```powershell
+# Create a mail-enabled security group and add the allowed mailboxes
+New-DistributionGroup -Name "MCP-Allowed-Mailboxes" -Type Security
+Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "user@org.com"
+Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "shared@org.com"
+
+# Restrict the app to only those mailboxes
+New-ApplicationAccessPolicy `
+  -AppId "<your-client-id>" `
+  -PolicyScopeGroupId "MCP-Allowed-Mailboxes" `
+  -AccessRight RestrictAccess `
+  -Description "Restrict MCP server to configured mailboxes"
+
+# Verify (should return Granted for allowed mailboxes)
+Test-ApplicationAccessPolicy -AppId "<your-client-id>" -Identity "user@org.com"
+```
+
+> **Note:** Policy changes can take up to 1 hour to propagate. Shared mailboxes must be added to the group directly.
+
+---
+
+## Security
+
+- Credentials are never logged. The server scrubs secrets, tokens, and email body content from all log output.
+- All Graph API calls use the `/users/{email}/...` path (application permissions), never `/me/`.
+- Write operations are blocked at the server level for any mailbox marked `readonly: true` in the config — this check happens before any network call is made.
+- The config file should be kept outside your project directory and never committed to source control. Use restrictive file permissions (`chmod 600` on Linux/macOS).
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamnetwork/m365-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for Microsoft 365 Email and Calendar access using client credentials (app-only auth). Supports multiple accounts, shared mailboxes, per-mailbox read-only access, folder navigation, and date/content filtering.",
   "type": "module",
   "main": "./dist/index.js",