setonc/outlook-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update README for v1.1.0 — 22 tools, mailbox params, architecture, shared scopes, .gitignore accuracy

Browse source
This commit is contained in:
Seton Carmichael 2026-08-25 15:02:08 -04:00
parent e70840552d
commit c112c9b330
1 changed files with 26 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
README.md
View file

@ -186,7 +186,7 @@ Each instance gets its own MSAL cache — no account-selection conflicts.
## Tools Reference ## Tools Reference
The server exposes **21 tools** across five categories. The server exposes **22 tools** across six categories (21 when `OUTLOOK_ENABLE_SHARED_MAILBOXES=false`).
### Authentication (3 tools) ### Authentication (3 tools)
@ -200,12 +200,12 @@ The server exposes **21 tools** across five categories.
| Tool | Key Parameters | Description | | Tool | Key Parameters | Description |
|---|---|---| |---|---|---|
| `list-emails` | `folder`, `count`, `dateFrom`, `dateTo`, `dateRange` | Lists emails from a folder with date filtering. Results include `conversationId`. | | `list-emails` | `folder`, `count`, `dateFrom`, `dateTo`, `dateRange`, `mailbox` | Lists emails from a folder with date filtering. Results include `conversationId`. Pass `mailbox` to target a shared mailbox. |
| `search-emails` | `query`, `from`, `to`, `subject`, `hasAttachments`, `unreadOnly`, `count` | Progressive search with KQL fallback strategies. Results include `conversationId`. | | `search-emails` | `query`, `from`, `to`, `subject`, `hasAttachments`, `unreadOnly`, `count`, `strict`, `mailbox` | Progressive search with KQL fallback strategies. Results include `conversationId`. Pass `mailbox` for shared mailbox search. Use `strict: true` to disable fallback to recent emails. |
| `read-email` | `id` | Reads a single email with full body (auto-cleaned HTML → text) | | `read-email` | `id`, `mailbox` | Reads a single email with full body (auto-cleaned HTML → text). Pass the same `mailbox` used when listing/searching. |
| `read-emails` | `ids` (max 10) | Reads multiple emails concurrently | | `read-emails` | `ids` (max 10), `mailbox` | Reads multiple emails concurrently |
| `send-email` | `to`, `cc`, `bcc`, `subject`, `body`, `importance`, `saveToSentItems` | Sends an email (plain text or HTML) | | `send-email` | `to`, `cc`, `bcc`, `subject`, `body`, `importance`, `saveToSentItems`, `mailbox`, `from`, `onBehalfOf` | Sends an email (plain text or HTML). When `mailbox` is set, sends as that shared mailbox via `users/{mailbox}/sendMail` (requires Send As + `Mail.Send.Shared`). Set `onBehalfOf: true` for Send on Behalf via `me/sendMail` with `from` set. |
| `get-email-thread` | `conversationId` (preferred) or `ids` (max 20) | Fetches a complete conversation across all folders (inbox + sent), strips quoted replies, deduplicates signatures per sender | | `get-email-thread` | `conversationId` (preferred) or `ids` (max 20), `mailbox` | Fetches a complete conversation across all folders (inbox + sent), strips quoted replies, deduplicates signatures per sender. Pass `mailbox` when the conversation is in a shared mailbox. |
**Date filtering** supports both ISO dates (`2024-06-15`) and relative ranges (`today`, `yesterday`, `last7days`, `last30days`, `thisweek`, `lastweek`, `thismonth`, `lastmonth`). **Date filtering** supports both ISO dates (`2024-06-15`) and relative ranges (`today`, `yesterday`, `last7days`, `last30days`, `thisweek`, `lastweek`, `thismonth`, `lastmonth`).
@ -226,9 +226,9 @@ The server exposes **21 tools** across five categories.
| Tool | Key Parameters | Description | | Tool | Key Parameters | Description |
|---|---|---| |---|---|---|
| `list-folders` | `includeItemCounts`, `includeChildren` | Lists mail folders (flat list or hierarchical tree) | | `list-folders` | `includeItemCounts`, `includeChildren`, `mailbox` | Lists mail folders (flat list or hierarchical tree). Pass `mailbox` for a shared mailbox's folders. |
| `create-folder` | `name`, `parentFolder` | Creates a new mail folder (optionally nested under a parent) | | `create-folder` | `name`, `parentFolder`, `mailbox` | Creates a new mail folder (optionally nested under a parent). There is no delete-folder tool — avoid test folders on shared mailboxes. |
| `move-emails` | `emailIds`, `targetFolder`, `sourceFolder` | Moves emails to a target folder by name | | `move-emails` | `emailIds`, `targetFolder`, `sourceFolder`, `mailbox` | Moves emails to a target folder by name within the same mailbox |
### Inbox Rules (3 tools) ### Inbox Rules (3 tools)
@ -238,6 +238,12 @@ The server exposes **21 tools** across five categories.
| `create-rule` | `name`, `fromAddresses`, `containsSubject`, `hasAttachments`, `moveToFolder`, `markAsRead`, `isEnabled`, `sequence` | Creates a new inbox rule | | `create-rule` | `name`, `fromAddresses`, `containsSubject`, `hasAttachments`, `moveToFolder`, `markAsRead`, `isEnabled`, `sequence` | Creates a new inbox rule |
| `edit-rule-sequence` | `ruleName`, `sequence` | Changes the execution order of an existing rule | | `edit-rule-sequence` | `ruleName`, `sequence` | Changes the execution order of an existing rule |
### Mailbox (1 tool, hidden when `OUTLOOK_ENABLE_SHARED_MAILBOXES=false`)
| Tool | Key Parameters | Description |
|---|---|---|
| `list-mailboxes` | `candidates` | Probes primary mailbox + `OUTLOOK_SHARED_MAILBOXES` seeds + local cache + optional `candidates[]` for read/folder access. Reports `sendAs` as `unverified` until a successful send. Graph cannot enumerate all mailboxes the user has rights to. |
## Architecture ## Architecture
``` ```
@ -274,6 +280,10 @@ folder/
create.js # create-folder handler create.js # create-folder handler
move.js # move-emails handler move.js # move-emails handler
mailbox/
index.js # Tool definition for list-mailboxes
list.js # list-mailboxes handler — probes primary, seeds, cache, candidates
rules/ rules/
index.js # Tool definitions for rules tools + edit-rule-sequence handler index.js # Tool definitions for rules tools + edit-rule-sequence handler
list.js # list-rules handler + getInboxRules() utility list.js # list-rules handler + getInboxRules() utility
@ -283,9 +293,12 @@ tools/
get-email-thread.js # get-email-thread tool — conversationId-based thread fetcher get-email-thread.js # get-email-thread tool — conversationId-based thread fetcher
utils/ utils/
graph-api.js # callGraphAPI() — HTTPS client for Microsoft Graph graph-api.js # callGraphAPI() — HTTPS client for Microsoft Graph (429/503 retry/backoff)
mailbox.js # normalizeMailbox(), buildPath(), withMailboxHeaders() — shared mailbox routing
bodyParser.js # HTML → text conversion, boilerplate/banner/legal block stripping, signature handling bodyParser.js # HTML → text conversion, boilerplate/banner/legal block stripping, signature handling
threadBuilder.js # Quote-boundary detection, unique-content extraction, chronological thread formatting threadBuilder.js # Quote-boundary detection, unique-content extraction, chronological thread formatting
time-formatter.js # Timezone-aware timestamp formatting for email/calendar display
timezone-mapper.js # Maps Windows timezone names to IANA for Intl-based date operations
odata-helpers.js # OData filter building, date parsing, relative date ranges odata-helpers.js # OData filter building, date parsing, relative date ranges
mock-data.js # Test mode mock responses mock-data.js # Test mode mock responses
``` ```
@ -324,8 +337,8 @@ Launches the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspecto
- **Token cache**: The `.outlook-mcp-tokens.json` file contains access and refresh tokens. It's in `.gitignore` by default. Protect it like a password. - **Token cache**: The `.outlook-mcp-tokens.json` file contains access and refresh tokens. It's in `.gitignore` by default. Protect it like a password.
- **No client secret in code**: For public client apps, no secret is needed. If you use a confidential client app, set `MS_CLIENT_SECRET` in the environment (not in the code). - **No client secret in code**: For public client apps, no secret is needed. If you use a confidential client app, set `MS_CLIENT_SECRET` in the environment (not in the code).
- **Scopes are hardcoded**: The OAuth scopes are defined in `config.js` and include read/write for mail and calendar. Adjust if you need fewer permissions. - **Scopes are conditional**: The OAuth scopes are defined in `config.js`. When `OUTLOOK_ENABLE_SHARED_MAILBOXES` is not `false`, the scope set includes `Mail.Read.Shared`, `Mail.ReadWrite.Shared`, and `Mail.Send.Shared`. Disable shared mailboxes to request a narrower scope set.
- **`.gitignore` covers**: `node_modules/`, `.env*`, `*.token.json`, `*.pem`, `*.key`, `.outlook-mcp-tokens.json` - **`.gitignore` covers**: `node_modules/`, `.env` / `.env.*`, `*.pem`, `*.key`, `*.cert`, `*.token.json`, `.outlook-mcp-tokens.json`
## Known Issues ## Known Issues