@mindstone/mcp-server-microsoft-mail 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-19
+
+### Documentation
+
+- Rewrote `README.md` to follow the structure in [`docs/CONNECTOR_README_GUIDE.md`](../../docs/CONNECTOR_README_GUIDE.md): added an npm-version badge, an italic positioning line, the `## Status` block with hyperlinked evidence and `Hosts tested` / `Machine-readable` rows, a `## Why this exists` section, an `## Example interaction` block, `## Host configuration examples` (Claude Desktop / Cursor and local development), the `(12)` tool count in the `## Tools` heading, and a `## Security notes` section.
+- Added the connector to the table in the repo-root `README.md`.
+
 ### Planned
 - Migrate to `@mindstone/mcp-server-microsoft-shared` from its npm-registry version once `0.1.0` of the shared package is published; the `0.1.0` cohort port currently consumes the shared package as a packed `file:` dependency.
 - Tighten Zod validation of Microsoft Graph response payloads in `0.2.0` or later.

package/README.md

@@ -1,18 +1,52 @@
 # @mindstone/mcp-server-microsoft-mail
 
+[![npm version](https://img.shields.io/npm/v/@mindstone/mcp-server-microsoft-mail.svg)](https://www.npmjs.com/package/@mindstone/mcp-server-microsoft-mail)
 [![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](./LICENSE)
 
 Microsoft 365 Outlook Mail MCP server — list, search, read, send, reply, forward, draft, move, and delete email via the Microsoft Graph API.
 
-Host-orchestrated OAuth, per-account credentials on disk, and a structured `auth_required` handoff so the host drives the sign-in flow rather than the server.
+*Cohort-style Microsoft 365 mail MCP. Host owns the OAuth flow, this server reads per-account tokens off disk, and each tool fails closed with a structured `auth_required` envelope so the host can drive reauth.*
 
 ## Status
 
-- **Version:** [0.1.0](./CHANGELOG.md)
+- **Version:** [0.1.1](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-microsoft-mail)
 - **Auth:** OAuth (host-orchestrated) ([`MS_CLIENT_ID`](./server.json))
-- **Tools:** 12 (list, search, get, send, reply, forward, draft, move, delete, folders)
+- **Tools:** [12](./src/tools.ts) (messages, folders, drafts)
 - **Surface:** cloud-api
-- **Shared library:** [`@mindstone/mcp-server-microsoft-shared`](../../packages/mcp-server-microsoft-shared)
+- **Hosts tested:** Mindstone Rebel
+- **Machine-readable:** [`STATUS.json`](./STATUS.json)
+- **Shared library:** [`@mindstone/mcp-server-microsoft-shared`](https://www.npmjs.com/package/@mindstone/mcp-server-microsoft-shared)
+
+## Why this exists
+
+When we ported this in May 2026, Microsoft's own [Graph MCP](https://github.com/microsoft/mcp) lineup did not yet ship a stand-alone Outlook Mail server, and the community options at the time each ran their own browser-callback server during OAuth — which our host application already does, with credentials it has already negotiated for the rest of the cohort. We pulled the bundled connector out of MindstoneRebel as a 1:1 port so the same five-connector Microsoft 365 cohort (mail, calendar, files, teams, SharePoint) shares a single OAuth surface, a single shared-library package for token persistence, request timeouts, and the structured `auth_required` envelope the host already knows how to recover from. This connector owns the cohort's authentication tool (`authenticate_microsoft_account`); the other four connectors reuse the credentials it negotiates.
+
+## Example interaction
+
+> "List my five most recent unread emails from Alice and reply to the latest one with 'thanks, will read tonight'."
+
+Tools the host calls:
+1. `search_emails` — `from:alice@example.com isRead:false`, top 5.
+2. `reply_to_email` — sends a reply on the top-result message ID with the supplied body.
+
+Response (trimmed):
+
+```json
+{
+  "matches": [
+    {
+      "id": "AAMkAD...",
+      "subject": "Q3 planning",
+      "from": "alice@example.com",
+      "receivedDateTime": "2026-05-19T09:14:11Z"
+    }
+  ],
+  "reply": {
+    "id": "AAMkAD...",
+    "isDraft": false
+  }
+}
+```
 
 ## Requirements
 
@@ -22,19 +56,26 @@ Host-orchestrated OAuth, per-account credentials on disk, and a structured `auth
 
 ## Quick Start
 
+### Install & build
+
 ```bash
 cd <path-to-repo>/connectors/microsoft-mail
 npm install
 npm run build
-node dist/index.js
 ```
 
-Once published:
+### npx (once published)
 
 ```bash
 npx -y @mindstone/mcp-server-microsoft-mail
 ```
 
+### Local
+
+```bash
+node dist/index.js
+```
+
 ## Configuration
 
 This server runs alongside a host application that owns the Microsoft 365 OAuth flow. The host writes credentials to disk; this server reads them.
@@ -55,7 +96,45 @@ This server runs alongside a host application that owns the Microsoft 365 OAuth
 | `MICROSOFT_REQUEST_TIMEOUT_MS` | Override the upstream Microsoft Graph request timeout (max `300000` ms). | `60000` |
 | `MICROSOFT_DISABLE_REFRESH` | Set to `1` to disable token refresh on this surface. Tools fail closed with the structured `auth_required` response so the host can drive reauth. Cloud surfaces set this to `1`. | unset |
 
-## Tools
+## Host configuration examples
+
+### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "Microsoft365Mail": {
+      "command": "npx",
+      "args": ["-y", "@mindstone/mcp-server-microsoft-mail"],
+      "env": {
+        "MS_CLIENT_ID": "your-entra-application-client-id",
+        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
+      }
+    }
+  }
+}
+```
+
+Until the host has written `${MS_CONFIG_DIR}/credentials/<account>.token.json` and `${MS_CONFIG_DIR}/accounts.json`, every tool call returns the structured `auth_required` response (the host's MCP service recognises this shape and dispatches to its registered Microsoft 365 OAuth orchestrator).
+
+### Local development (no npm publish needed)
+
+```json
+{
+  "mcpServers": {
+    "Microsoft365Mail": {
+      "command": "node",
+      "args": ["<path-to-repo>/connectors/microsoft-mail/dist/index.js"],
+      "env": {
+        "MS_CLIENT_ID": "your-entra-application-client-id",
+        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
+      }
+    }
+  }
+}
+```
+
+## Tools (12)
 
 | Tool | Description |
 | ---- | ----------- |
@@ -72,6 +151,13 @@ This server runs alongside a host application that owns the Microsoft 365 OAuth
 | `create_reply_draft` | Save a draft reply to an existing email. |
 | `create_draft` | Save a new standalone draft email. |
 
-## License
+## Security notes
+
+- Token files are written by the host with mode `0600`; this server reads them via the cohort-shared library, which fails closed on malformed files.
+- `MICROSOFT_DISABLE_REFRESH=1` is the default on cloud surfaces so the desktop session remains the sole refresh-token authority and avoids racing for single-use refresh tokens.
+- Successful tool responses drop the OSS-only `ok:true` wrapper to match the bundled `successResult` shape; manual validation/business errors return `isError:true` with a `{ ok:false, error, action_required, next_step }` payload so the host's recovery layer can act on them.
+- Per-tool Graph calls run under a composed caller + cohort timeout signal via `.options({signal})` plus a `Promise.race` wrapper for defence-in-depth.
+
+## Licence
 
-[FSL-1.1-MIT](./LICENSE) — Functional Source License, MIT Future License (4-year transition). Free for non-competing use; relicenses to MIT after the transition window.
+[FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. Free for non-competing use; relicenses to MIT on the converter date in `LICENSE`.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@mindstone/mcp-server-microsoft-mail",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "mcpName": "io.github.mindstone/mcp-server-microsoft-mail",
-  "description": "Microsoft 365 Outlook Mail MCP server — read, search, send, reply, forward, draft, move, and delete email via Microsoft Graph",
+  "description": "Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.",
   "license": "FSL-1.1-MIT",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "security:internal-refs": "node scripts/check-internal-refs.mjs"
   },
   "dependencies": {
-    "@mindstone/mcp-server-microsoft-shared": "^0.1.0",
+    "@mindstone/mcp-server-microsoft-shared": "0.1.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "zod": "^3.23.0"
   },

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.mindstone/mcp-server-microsoft-mail",
   "title": "Microsoft 365 Mail",
-  "description": "Microsoft 365 Outlook Mail MCP server: list, search, read, send, reply, forward, draft, move, and delete email via Microsoft Graph",
-  "version": "0.1.0",
+  "description": "Microsoft 365 Outlook mail via Graph: read, search, send, reply, forward, draft, move, delete.",
+  "version": "0.1.1",
   "repository": {
     "url": "https://github.com/mindstone/mcp-servers",
     "source": "github",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@mindstone/mcp-server-microsoft-mail",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"