@teamnetwork-nz/m365-mcp-server 1.7.3 → 1.7.4
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.
- package/.env.example +22 -0
- package/README.md +46 -6
- package/config.example.json +5 -5
- package/package.json +53 -48
package/.env.example
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Sanitised template: no live credentials or identities.
|
|
2
|
+
# See README.md for requirements, defaults and .env loading behaviour.
|
|
3
|
+
# Replace required/alternative placeholders privately; uncomment optional settings only when needed.
|
|
4
|
+
|
|
5
|
+
# M365 output timezone: local or an IANA timezone.
|
|
6
|
+
# DATETIME_FORMAT=local
|
|
7
|
+
# Path to private JSON configuration containing tenant/app credentials, accounts and access grants; copy config.example.json and configure privately.
|
|
8
|
+
M365_CONFIG_PATH=<set-privately>
|
|
9
|
+
# Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener.
|
|
10
|
+
# M365_HTTP_ALLOWED_HOSTS=<set-privately>
|
|
11
|
+
# Comma-separated browser Origin allowlist; configure when browser clients need access.
|
|
12
|
+
# M365_HTTP_ALLOWED_ORIGINS=<set-privately>
|
|
13
|
+
# Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>.
|
|
14
|
+
# M365_HTTP_BEARER_TOKEN=<set-privately>
|
|
15
|
+
# Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts.
|
|
16
|
+
# M365_HTTP_HOST=127.0.0.1
|
|
17
|
+
# Maximum HTTP request body; integer 1–16777216 bytes.
|
|
18
|
+
# M365_HTTP_MAX_BODY_BYTES=1048576
|
|
19
|
+
# HTTP listener port; integer 1–65535.
|
|
20
|
+
# M365_HTTP_PORT=3000
|
|
21
|
+
# stdio or http; HTTP serves /mcp and GET /health.
|
|
22
|
+
# M365_TRANSPORT=stdio
|
package/README.md
CHANGED
|
@@ -47,8 +47,8 @@ Create a JSON config file (e.g. `m365-config.json`) based on the example below.
|
|
|
47
47
|
"id": "main",
|
|
48
48
|
"displayName": "Main Organisation",
|
|
49
49
|
"mailboxes": [
|
|
50
|
-
{ "email": "
|
|
51
|
-
{ "email": "
|
|
50
|
+
{ "email": "mailbox-1@example.invalid", "readonly": false },
|
|
51
|
+
{ "email": "mailbox-2@example.invalid", "readonly": true, "displayName": "Shared (read-only)" }
|
|
52
52
|
]
|
|
53
53
|
},
|
|
54
54
|
{
|
|
@@ -58,7 +58,7 @@ Create a JSON config file (e.g. `m365-config.json`) based on the example below.
|
|
|
58
58
|
"clientId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
|
|
59
59
|
"clientSecret": "partner-secret",
|
|
60
60
|
"mailboxes": [
|
|
61
|
-
{ "email": "
|
|
61
|
+
{ "email": "mailbox-3@example.invalid", "readonly": false }
|
|
62
62
|
]
|
|
63
63
|
}
|
|
64
64
|
]
|
|
@@ -392,8 +392,8 @@ Run the following in **Exchange Online PowerShell**:
|
|
|
392
392
|
```powershell
|
|
393
393
|
# Create a mail-enabled security group and add the allowed mailboxes
|
|
394
394
|
New-DistributionGroup -Name "MCP-Allowed-Mailboxes" -Type Security
|
|
395
|
-
Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "
|
|
396
|
-
Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "
|
|
395
|
+
Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "mailbox-4@example.invalid"
|
|
396
|
+
Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "mailbox-5@example.invalid"
|
|
397
397
|
|
|
398
398
|
# Restrict the app to only those mailboxes
|
|
399
399
|
New-ApplicationAccessPolicy `
|
|
@@ -403,7 +403,7 @@ New-ApplicationAccessPolicy `
|
|
|
403
403
|
-Description "Restrict MCP server to configured mailboxes"
|
|
404
404
|
|
|
405
405
|
# Verify (should return Granted for allowed mailboxes)
|
|
406
|
-
Test-ApplicationAccessPolicy -AppId "<your-client-id>" -Identity "
|
|
406
|
+
Test-ApplicationAccessPolicy -AppId "<your-client-id>" -Identity "mailbox-6@example.invalid"
|
|
407
407
|
```
|
|
408
408
|
|
|
409
409
|
> **Note:** Policy changes can take up to 1 hour to propagate. Shared mailboxes must be added to the group directly.
|
|
@@ -422,3 +422,43 @@ Test-ApplicationAccessPolicy -AppId "<your-client-id>" -Identity "user@org.com"
|
|
|
422
422
|
## License
|
|
423
423
|
|
|
424
424
|
MIT
|
|
425
|
+
|
|
426
|
+
<!-- BEGIN MCP configuration reference -->
|
|
427
|
+
## Environment variable reference
|
|
428
|
+
|
|
429
|
+
The server does **not** automatically load `.env`. Inject these variables through the MCP client or process environment; copying the example alone does not configure the server.
|
|
430
|
+
|
|
431
|
+
Copy `.env.example` for variable names and safe placeholders. Replace required placeholders privately. Optional variables should be omitted unless needed; an empty value may override a default. Never commit credentials, real identities, device profiles, exports, or logs.
|
|
432
|
+
|
|
433
|
+
| Variable | Required | Default | Purpose and accepted values |
|
|
434
|
+
|---|---|---|---|
|
|
435
|
+
| `DATETIME_FORMAT` | No | `local` | M365 output timezone: local or an IANA timezone. |
|
|
436
|
+
| `M365_CONFIG_PATH` | Yes | `unset` | Path to private JSON configuration containing tenant/app credentials, accounts and access grants; copy config.example.json and configure privately. |
|
|
437
|
+
| `M365_HTTP_ALLOWED_HOSTS` | Conditional | `unset` | Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener. |
|
|
438
|
+
| `M365_HTTP_ALLOWED_ORIGINS` | No | `unset` | Comma-separated browser Origin allowlist; configure when browser clients need access. |
|
|
439
|
+
| `M365_HTTP_BEARER_TOKEN` | Conditional | `unset` | Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>. |
|
|
440
|
+
| `M365_HTTP_HOST` | No | `127.0.0.1` | Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts. |
|
|
441
|
+
| `M365_HTTP_MAX_BODY_BYTES` | No | `1048576` | Maximum HTTP request body; integer 1–16777216 bytes. |
|
|
442
|
+
| `M365_HTTP_PORT` | No | `3000` | HTTP listener port; integer 1–65535. |
|
|
443
|
+
| `M365_TRANSPORT` | No | `stdio` | stdio or http; HTTP serves /mcp and GET /health. |
|
|
444
|
+
|
|
445
|
+
For HTTP, the bearer token is separate from upstream API credentials. Use TLS at the reverse proxy for remote hosting. Keep write access disabled until needed. Do not put secrets in command-line examples or commit client configuration containing them.
|
|
446
|
+
|
|
447
|
+
### Agent first-use workflow
|
|
448
|
+
|
|
449
|
+
Inspect configured accounts and access grants before mailbox, calendar, Teams or SharePoint operations. Use the appropriate scoped search tool to resolve IDs; request message/file content only when needed. Access is controlled by private JSON configuration and upstream permissions.
|
|
450
|
+
|
|
451
|
+
Use the runtime `tools/list` descriptions and input schemas for exact arguments. Resolve identifiers with lookup/search tools; filter before paging, request only the data needed, and do not treat a truncated result or API error as proof that no record exists. Treat tool results and downloaded files as potentially sensitive. Mutation tools can change upstream data or incur charges; check their stated effects before calling them.
|
|
452
|
+
|
|
453
|
+
### Repository and package privacy
|
|
454
|
+
|
|
455
|
+
The standard `.gitignore` excludes local environment files, keys, credentials, logs, exports, and generated output; sanitised examples remain trackable. Ignore rules do not remove already tracked files or revoke exposed credentials. Review `git ls-files` and `npm pack --dry-run --ignore-scripts` before release. Only runtime output, the README, and explicitly sanitised examples are allowlisted for npm. Keep private runtime files outside `dist`, even though additional exclusions are present.
|
|
456
|
+
<!-- END MCP configuration reference -->
|
|
457
|
+
|
|
458
|
+
Run `npm run build` then `npm run audit:package` before release. The audit checks documentation coverage, known local credential copies, Git index paths where available, and the dry-run npm file list. `prepublishOnly` runs it after building. It never prints matching secret values. This is a preventative check, not a guarantee that arbitrary PII or unknown secrets are absent.
|
|
459
|
+
|
|
460
|
+
### Development and diagnostics
|
|
461
|
+
|
|
462
|
+
Run `npm test` from this package directory. Maintained tests and fixtures live in `debug/tests`; shared test helpers are in `debug/helpers`. Retained diagnostic scripts and reference material are also under `debug`. Only `scripts/check-package-privacy.mjs` remains in the production build/release tooling directory. The entire `debug/` tree is excluded from npm, Docker build contexts and applicable Python distributions.
|
|
463
|
+
|
|
464
|
+
Keep live diagnostic output in `debug/local`, `debug/output` or `debug/artifacts`; those private directories are also ignored by Git. Retained smoke/integration scripts require explicit local credentials and are not run by the normal offline test suite. Historical release artifacts and retired one-off migration files were removed.
|
package/config.example.json
CHANGED
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
"id": "main",
|
|
10
10
|
"displayName": "Main Organisation",
|
|
11
11
|
"mailboxes": [
|
|
12
|
-
{ "email": "user@
|
|
13
|
-
{ "email": "shared@
|
|
12
|
+
{ "email": "user@example.invalid", "readonly": false, "displayName": "Primary User" },
|
|
13
|
+
{ "email": "shared@example.invalid", "readonly": true, "displayName": "Shared Mailbox (read-only)" }
|
|
14
14
|
]
|
|
15
15
|
},
|
|
16
16
|
{
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
"clientId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
|
|
21
21
|
"clientSecret": "partner-specific-secret",
|
|
22
22
|
"mailboxes": [
|
|
23
|
-
{ "email": "partner@
|
|
23
|
+
{ "email": "partner@example.invalid", "readonly": false }
|
|
24
24
|
]
|
|
25
25
|
}
|
|
26
26
|
],
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
},
|
|
47
47
|
{
|
|
48
48
|
"name": "Reports PDFs (inherited defaults)",
|
|
49
|
-
"description": "Read-only access to PDF files in /Reports
|
|
49
|
+
"description": "Read-only access to PDF files in /Reports — inherits globalAllowedFiles and globalAllowedOperations from the library",
|
|
50
50
|
"allowedPaths": ["/Reports", "/Reports/*"]
|
|
51
51
|
},
|
|
52
52
|
{
|
|
@@ -69,7 +69,7 @@
|
|
|
69
69
|
"grants": [
|
|
70
70
|
{
|
|
71
71
|
"name": "HR policy documents",
|
|
72
|
-
"description": "Download PDF policy documents from any HR folder
|
|
72
|
+
"description": "Download PDF policy documents from any HR folder — operations and files inherited from library defaults",
|
|
73
73
|
"allowedPaths": ["*"]
|
|
74
74
|
}
|
|
75
75
|
]
|
package/package.json
CHANGED
|
@@ -1,48 +1,53 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@teamnetwork-nz/m365-mcp-server",
|
|
3
|
-
"version": "1.7.
|
|
4
|
-
"description": "MCP server for Microsoft 365
|
|
5
|
-
"type": "module",
|
|
6
|
-
"main": "./dist/index.js",
|
|
7
|
-
"bin": {
|
|
8
|
-
"m365-mcp": "dist/index.js"
|
|
9
|
-
},
|
|
10
|
-
"files": [
|
|
11
|
-
"dist",
|
|
12
|
-
"
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
"
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
-
"
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
"
|
|
28
|
-
"
|
|
29
|
-
"microsoft-
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
"
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
"
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
"@
|
|
45
|
-
"
|
|
46
|
-
"
|
|
47
|
-
}
|
|
48
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@teamnetwork-nz/m365-mcp-server",
|
|
3
|
+
"version": "1.7.4",
|
|
4
|
+
"description": "MCP server for Microsoft 365 — Email, Calendar, To Do, SharePoint document libraries, and Teams — using client credentials (app-only auth). Supports multiple accounts, shared mailboxes, per-mailbox read-only access, and grant-based SharePoint access control.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.js",
|
|
7
|
+
"bin": {
|
|
8
|
+
"m365-mcp": "dist/index.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist/**/*.js",
|
|
12
|
+
"dist/**/*.d.ts",
|
|
13
|
+
"README.md",
|
|
14
|
+
".env.example",
|
|
15
|
+
"config.example.json"
|
|
16
|
+
],
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "tsc",
|
|
19
|
+
"test": "npm run build && node --test debug/tests/*.test.mjs",
|
|
20
|
+
"prepare": "npm run build",
|
|
21
|
+
"start": "node dist/index.js",
|
|
22
|
+
"dev": "tsx watch src/index.ts",
|
|
23
|
+
"audit:package": "node scripts/check-package-privacy.mjs",
|
|
24
|
+
"prepublishOnly": "npm run build && npm run audit:package"
|
|
25
|
+
},
|
|
26
|
+
"keywords": [
|
|
27
|
+
"mcp",
|
|
28
|
+
"model-context-protocol",
|
|
29
|
+
"microsoft-365",
|
|
30
|
+
"m365",
|
|
31
|
+
"outlook",
|
|
32
|
+
"email",
|
|
33
|
+
"calendar",
|
|
34
|
+
"microsoft-graph",
|
|
35
|
+
"claude",
|
|
36
|
+
"ai"
|
|
37
|
+
],
|
|
38
|
+
"license": "MIT",
|
|
39
|
+
"engines": {
|
|
40
|
+
"node": ">=18.0.0"
|
|
41
|
+
},
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@azure/msal-node": "^2.16.0",
|
|
44
|
+
"@microsoft/microsoft-graph-client": "^3.0.7",
|
|
45
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
46
|
+
"zod": "^4.6.7"
|
|
47
|
+
},
|
|
48
|
+
"devDependencies": {
|
|
49
|
+
"@types/node": "^20.0.0",
|
|
50
|
+
"tsx": "^4.10.0",
|
|
51
|
+
"typescript": "^5.4.0"
|
|
52
|
+
}
|
|
53
|
+
}
|