@teamnetwork-nz/mailstore-spe-mcp 0.1.0
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/README.md +360 -0
- package/dist/config/env.d.ts +14 -0
- package/dist/config/env.js +45 -0
- package/dist/config/env.js.map +1 -0
- package/dist/config/schema.d.ts +86 -0
- package/dist/config/schema.js +55 -0
- package/dist/config/schema.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +60 -0
- package/dist/index.js.map +1 -0
- package/dist/logging/logger.d.ts +12 -0
- package/dist/logging/logger.js +80 -0
- package/dist/logging/logger.js.map +1 -0
- package/dist/mailstore/authentication.d.ts +7 -0
- package/dist/mailstore/authentication.js +15 -0
- package/dist/mailstore/authentication.js.map +1 -0
- package/dist/mailstore/capability-registry.d.ts +40 -0
- package/dist/mailstore/capability-registry.js +152 -0
- package/dist/mailstore/capability-registry.js.map +1 -0
- package/dist/mailstore/client.d.ts +33 -0
- package/dist/mailstore/client.js +274 -0
- package/dist/mailstore/client.js.map +1 -0
- package/dist/mailstore/encoder.d.ts +14 -0
- package/dist/mailstore/encoder.js +42 -0
- package/dist/mailstore/encoder.js.map +1 -0
- package/dist/mailstore/errors.d.ts +44 -0
- package/dist/mailstore/errors.js +49 -0
- package/dist/mailstore/errors.js.map +1 -0
- package/dist/mailstore/instance-resolver.d.ts +43 -0
- package/dist/mailstore/instance-resolver.js +143 -0
- package/dist/mailstore/instance-resolver.js.map +1 -0
- package/dist/mailstore/metadata.d.ts +21 -0
- package/dist/mailstore/metadata.js +50 -0
- package/dist/mailstore/metadata.js.map +1 -0
- package/dist/mailstore/operation-poller.d.ts +19 -0
- package/dist/mailstore/operation-poller.js +72 -0
- package/dist/mailstore/operation-poller.js.map +1 -0
- package/dist/mailstore/response-parser.d.ts +11 -0
- package/dist/mailstore/response-parser.js +66 -0
- package/dist/mailstore/response-parser.js.map +1 -0
- package/dist/mailstore/types.d.ts +79 -0
- package/dist/mailstore/types.js +6 -0
- package/dist/mailstore/types.js.map +1 -0
- package/dist/output/normalizers.d.ts +11 -0
- package/dist/output/normalizers.js +40 -0
- package/dist/output/normalizers.js.map +1 -0
- package/dist/output/tool-result.d.ts +30 -0
- package/dist/output/tool-result.js +24 -0
- package/dist/output/tool-result.js.map +1 -0
- package/dist/output/truncation.d.ts +17 -0
- package/dist/output/truncation.js +27 -0
- package/dist/output/truncation.js.map +1 -0
- package/dist/policy/access-mode.d.ts +16 -0
- package/dist/policy/access-mode.js +21 -0
- package/dist/policy/access-mode.js.map +1 -0
- package/dist/policy/confirmations.d.ts +24 -0
- package/dist/policy/confirmations.js +49 -0
- package/dist/policy/confirmations.js.map +1 -0
- package/dist/policy/redaction.d.ts +15 -0
- package/dist/policy/redaction.js +63 -0
- package/dist/policy/redaction.js.map +1 -0
- package/dist/policy/tool-policy.d.ts +15 -0
- package/dist/policy/tool-policy.js +2 -0
- package/dist/policy/tool-policy.js.map +1 -0
- package/dist/resources/health.d.ts +17 -0
- package/dist/resources/health.js +55 -0
- package/dist/resources/health.js.map +1 -0
- package/dist/resources/register-resources.d.ts +7 -0
- package/dist/resources/register-resources.js +37 -0
- package/dist/resources/register-resources.js.map +1 -0
- package/dist/server.d.ts +17 -0
- package/dist/server.js +62 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/compliance.d.ts +6 -0
- package/dist/tools/compliance.js +96 -0
- package/dist/tools/compliance.js.map +1 -0
- package/dist/tools/instances.d.ts +4 -0
- package/dist/tools/instances.js +197 -0
- package/dist/tools/instances.js.map +1 -0
- package/dist/tools/jobs.d.ts +2 -0
- package/dist/tools/jobs.js +125 -0
- package/dist/tools/jobs.js.map +1 -0
- package/dist/tools/maintenance.d.ts +3 -0
- package/dist/tools/maintenance.js +22 -0
- package/dist/tools/maintenance.js.map +1 -0
- package/dist/tools/platform.d.ts +4 -0
- package/dist/tools/platform.js +134 -0
- package/dist/tools/platform.js.map +1 -0
- package/dist/tools/profiles.d.ts +2 -0
- package/dist/tools/profiles.js +140 -0
- package/dist/tools/profiles.js.map +1 -0
- package/dist/tools/raw-api.d.ts +16 -0
- package/dist/tools/raw-api.js +109 -0
- package/dist/tools/raw-api.js.map +1 -0
- package/dist/tools/register-tools.d.ts +14 -0
- package/dist/tools/register-tools.js +121 -0
- package/dist/tools/register-tools.js.map +1 -0
- package/dist/tools/smtp.d.ts +2 -0
- package/dist/tools/smtp.js +39 -0
- package/dist/tools/smtp.js.map +1 -0
- package/dist/tools/stores.d.ts +2 -0
- package/dist/tools/stores.js +116 -0
- package/dist/tools/stores.js.map +1 -0
- package/dist/tools/tool.d.ts +41 -0
- package/dist/tools/tool.js +33 -0
- package/dist/tools/tool.js.map +1 -0
- package/dist/tools/users.d.ts +2 -0
- package/dist/tools/users.js +266 -0
- package/dist/tools/users.js.map +1 -0
- package/package.json +52 -0
package/README.md
ADDED
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
# MailStore SPE MCP Server
|
|
2
|
+
|
|
3
|
+
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides a **curated, safety-gated administrator interface** over the **MailStore Service Provider Edition (SPE) 26.3 Management API**.
|
|
4
|
+
|
|
5
|
+
It is deliberately opinionated: rather than exposing every raw API function, it offers a concise set of high-level tools suitable for reliable LLM use — multi-instance aware, **read-only by default**, with graduated access modes, exact confirmation strings for state changes, capability discovery against live metadata, and bounded, structured, secret-free output.
|
|
6
|
+
|
|
7
|
+
Verified against a live MailStore SPE **26.3.1.24182** installation.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Contents
|
|
12
|
+
|
|
13
|
+
- [Architecture](#architecture)
|
|
14
|
+
- [Prerequisites](#prerequisites)
|
|
15
|
+
- [MailStore account setup](#mailstore-account-setup)
|
|
16
|
+
- [Configuration](#configuration)
|
|
17
|
+
- [Access modes](#access-modes)
|
|
18
|
+
- [Running locally (stdio)](#running-locally-stdio)
|
|
19
|
+
- [Docker deployment](#docker-deployment)
|
|
20
|
+
- [Supergateway + Caddy](#supergateway--caddy)
|
|
21
|
+
- [RooCode / Cline configuration](#roocode--cline-configuration)
|
|
22
|
+
- [Tool catalogue](#tool-catalogue)
|
|
23
|
+
- [Confirmation model](#confirmation-model)
|
|
24
|
+
- [Resources](#resources)
|
|
25
|
+
- [Error model](#error-model)
|
|
26
|
+
- [Development & testing](#development--testing)
|
|
27
|
+
- [Troubleshooting](#troubleshooting)
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Architecture
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
RooCode / Cline
|
|
35
|
+
│ SSE
|
|
36
|
+
▼
|
|
37
|
+
Caddy (TLS, access control)
|
|
38
|
+
│
|
|
39
|
+
▼
|
|
40
|
+
Supergateway (SSE ⇄ stdio)
|
|
41
|
+
│ stdio
|
|
42
|
+
▼
|
|
43
|
+
mailstore-spe-mcp ← this project
|
|
44
|
+
│ HTTPS + Basic auth
|
|
45
|
+
▼
|
|
46
|
+
MailStore SPE Management Server (:8474)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Internally the server is layered so the MailStore client is independent of the MCP SDK:
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
src/
|
|
53
|
+
config/ env parsing & validation (Zod)
|
|
54
|
+
mailstore/ client, encoder, response-parser, operation-poller,
|
|
55
|
+
metadata, capability-registry, instance-resolver, errors
|
|
56
|
+
policy/ access-mode, tool-policy (risk classes), confirmations, redaction
|
|
57
|
+
output/ tool-result, truncation, normalizers
|
|
58
|
+
tools/ platform, instances, users, profiles, jobs, stores, smtp,
|
|
59
|
+
compliance, maintenance, raw-api, register-tools
|
|
60
|
+
resources/ health + read-only resources
|
|
61
|
+
server.ts wires everything together
|
|
62
|
+
index.ts stdio bootstrap
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Prerequisites
|
|
68
|
+
|
|
69
|
+
- Node.js 22 LTS (for local runs) or Docker
|
|
70
|
+
- Network reachability to the MailStore SPE Management API over HTTPS (default TCP **8474**)
|
|
71
|
+
- A dedicated MailStore SPE **system administrator** account (see below)
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## MailStore account setup
|
|
76
|
+
|
|
77
|
+
Use a **dedicated** SPE system administrator account for the MCP — not a personal admin login.
|
|
78
|
+
|
|
79
|
+
- The Management API uses **HTTP Basic authentication over HTTPS**.
|
|
80
|
+
- Where MFA is enabled for the system administrator, you must use the administrator's **API password** rather than the interactive password. The MailStore API exposes `CreateSystemAdministratorAPIPassword` to generate one.
|
|
81
|
+
- Grant the account only the privileges the deployment needs. Read-only monitoring needs far less than administrator mode.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Configuration
|
|
86
|
+
|
|
87
|
+
All configuration comes from environment variables (or Docker secrets). Copy `.env.example` to `.env` and fill it in. **`MAILSTORE_BASE_URL` must not include `/api`.**
|
|
88
|
+
|
|
89
|
+
### Required
|
|
90
|
+
|
|
91
|
+
| Variable | Description |
|
|
92
|
+
|----------|-------------|
|
|
93
|
+
| `MAILSTORE_BASE_URL` | e.g. `https://mailstore.example.com:8474` (HTTPS, no `/api`) |
|
|
94
|
+
| `MAILSTORE_USERNAME` | SPE administrator / API account username |
|
|
95
|
+
| `MAILSTORE_PASSWORD` | Password or API password (never logged) |
|
|
96
|
+
|
|
97
|
+
### Recommended
|
|
98
|
+
|
|
99
|
+
| Variable | Default | Description |
|
|
100
|
+
|----------|---------|-------------|
|
|
101
|
+
| `MAILSTORE_VERIFY_TLS` | `true` | Verify the server certificate. Disable only in a lab. |
|
|
102
|
+
| `MAILSTORE_CA_FILE` | — | Path to a custom CA bundle (PEM). |
|
|
103
|
+
| `MAILSTORE_REQUEST_TIMEOUT_MS` | `30000` | Per-request timeout. |
|
|
104
|
+
| `MAILSTORE_LONG_POLL_TIMEOUT_MS` | `25000` | Long-poll window for async operations. |
|
|
105
|
+
| `MAILSTORE_OPERATION_TIMEOUT_MS` | `1800000` | Overall timeout for long-running operations. |
|
|
106
|
+
| `MAILSTORE_METADATA_CACHE_TTL_SECONDS` | `3600` | Metadata cache TTL. |
|
|
107
|
+
| `MAILSTORE_INSTANCE_CACHE_TTL_SECONDS` | `60` | Instance-list cache TTL. |
|
|
108
|
+
| `MCP_ACCESS_MODE` | `read-only` | `read-only` \| `operator` \| `administrator`. |
|
|
109
|
+
| `MCP_ENABLE_RAW_API` | `false` | Enable the generic escape-hatch tool. |
|
|
110
|
+
| `MCP_ALLOW_DESTRUCTIVE` | `false` | Permit destructive tools. |
|
|
111
|
+
| `MCP_ALLOW_BULK_INSTANCE_ACTIONS` | `false` | Reserved; first release keeps single-target only. |
|
|
112
|
+
| `MCP_MAX_RESULT_ITEMS` | `200` | Cap on list results before truncation. |
|
|
113
|
+
| `LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error`. |
|
|
114
|
+
| `LOG_FORMAT` | `json` | `json` \| `pretty`. |
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Access modes
|
|
119
|
+
|
|
120
|
+
Tools are registered — and therefore visible to the model — only when the current mode permits them. Read-only mode exposes **no** mutating tools at all.
|
|
121
|
+
|
|
122
|
+
| Mode | Adds |
|
|
123
|
+
|------|------|
|
|
124
|
+
| `read-only` | Retrieval, reporting, health checks. |
|
|
125
|
+
| `operator` | Run profile/job, cancel job, test SMTP, dry-run directory sync, verify a store, refresh statistics, start/stop/restart a single instance. |
|
|
126
|
+
| `administrator` | Create/update/delete users, set passwords, apply directory sync, change retention policies. |
|
|
127
|
+
|
|
128
|
+
Destructive tools (`mailstore_delete_user`, `mailstore_verify_all_stores`, `mailstore_set_retention_policies`) additionally require `MCP_ALLOW_DESTRUCTIVE=true`, and are not registered otherwise.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Running locally (stdio)
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
npm install
|
|
136
|
+
npm run build
|
|
137
|
+
MAILSTORE_BASE_URL=https://mailstore.example.com:8474 \
|
|
138
|
+
MAILSTORE_USERNAME=mcp-api \
|
|
139
|
+
MAILSTORE_PASSWORD=... \
|
|
140
|
+
MCP_ACCESS_MODE=read-only \
|
|
141
|
+
npm start
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Or in watch mode during development: `npm run dev`.
|
|
145
|
+
|
|
146
|
+
The process communicates over stdio: **stdout carries only MCP protocol messages; all logs go to stderr.**
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Docker deployment
|
|
151
|
+
|
|
152
|
+
Multi-stage build, runs as the non-root `node` user, no credentials baked in:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
docker build -t teamnetwork/mailstore-spe-mcp:latest .
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
See [`docker-compose.example.yml`](docker-compose.example.yml) for a full stack. Provide secrets via environment or Docker secrets.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Supergateway + Caddy
|
|
163
|
+
|
|
164
|
+
RooCode requires SSE. Supergateway converts the stdio server to SSE; Caddy terminates TLS and restricts access. Suggested hostname:
|
|
165
|
+
|
|
166
|
+
```
|
|
167
|
+
https://mcp-mailstore.ai.example.net.nz/sse
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Minimal `Caddyfile`:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
mcp-mailstore.ai.example.net.nz {
|
|
174
|
+
# import your standard auth / IP allowlist snippet here
|
|
175
|
+
encode gzip
|
|
176
|
+
reverse_proxy mailstore-mcp:8115 {
|
|
177
|
+
# SSE needs unbuffered, HTTP/1.1 proxying
|
|
178
|
+
flush_interval -1
|
|
179
|
+
transport http {
|
|
180
|
+
versions 1.1
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Supergateway command (see compose file):
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
--stdio "node dist/index.js" --port 8115 --cors --healthEndpoint /healthz
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
The MCP server must not assume it is directly exposed to the Internet — always front it with Caddy.
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## RooCode / Cline configuration
|
|
197
|
+
|
|
198
|
+
RooCode (SSE):
|
|
199
|
+
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"mcpServers": {
|
|
203
|
+
"mailstore-spe": {
|
|
204
|
+
"type": "sse",
|
|
205
|
+
"url": "https://mcp-mailstore.ai.example.net.nz/sse",
|
|
206
|
+
"timeout": 60
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Cline (stdio, running the built server directly):
|
|
213
|
+
|
|
214
|
+
```json
|
|
215
|
+
{
|
|
216
|
+
"mcpServers": {
|
|
217
|
+
"mailstore-spe": {
|
|
218
|
+
"command": "node",
|
|
219
|
+
"args": ["/app/dist/index.js"],
|
|
220
|
+
"env": {
|
|
221
|
+
"MAILSTORE_BASE_URL": "https://mailstore.example.com:8474",
|
|
222
|
+
"MAILSTORE_USERNAME": "mcp-api",
|
|
223
|
+
"MAILSTORE_PASSWORD": "...",
|
|
224
|
+
"MCP_ACCESS_MODE": "read-only"
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
Adjust key names to your client's current schema.
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## Tool catalogue
|
|
236
|
+
|
|
237
|
+
Every instance-scoped tool takes an `instance` selector (exact instanceID, alias, or display name — resolved to exactly one instance; ambiguous names are rejected). Tools requiring confirmation take a `confirmation` string (see below).
|
|
238
|
+
|
|
239
|
+
| Tool | Mode | Notes |
|
|
240
|
+
|------|------|-------|
|
|
241
|
+
| `mailstore_ping` | read-only | Connectivity + auth check. |
|
|
242
|
+
| `mailstore_get_environment` | read-only | Version / environment. |
|
|
243
|
+
| `mailstore_get_service_status` | read-only | SPE service status. |
|
|
244
|
+
| `mailstore_get_platform_summary` | read-only | Composed platform overview. |
|
|
245
|
+
| `mailstore_list_instances` | read-only | Instances with state filter/search. |
|
|
246
|
+
| `mailstore_get_instance` | read-only | Config + optional stats/stores (sizes off by default). |
|
|
247
|
+
| `mailstore_get_instance_statistics` | read-only | Archive statistics. |
|
|
248
|
+
| `mailstore_list_users` | read-only | |
|
|
249
|
+
| `mailstore_get_user` | read-only | |
|
|
250
|
+
| `mailstore_list_profiles` | read-only | |
|
|
251
|
+
| `mailstore_get_profile_results` | read-only | Worker results (handles `timeZoneID` spelling). |
|
|
252
|
+
| `mailstore_list_jobs` | read-only | |
|
|
253
|
+
| `mailstore_get_job_results` | read-only | |
|
|
254
|
+
| `mailstore_list_stores` | read-only | `includeSize` off by default (slow). |
|
|
255
|
+
| `mailstore_get_smtp_settings` | read-only | Secrets redacted. |
|
|
256
|
+
| `mailstore_get_compliance` | read-only | Compliance + retention + policy hash. |
|
|
257
|
+
| `mailstore_start_instance` | operator | Single instance; confirm `START <id>`. |
|
|
258
|
+
| `mailstore_stop_instance` | operator | Single instance; confirm `STOP <id>`. |
|
|
259
|
+
| `mailstore_restart_instance` | operator | Single instance; confirm `RESTART <id>`. |
|
|
260
|
+
| `mailstore_run_profile` | operator | Confirm `RUN PROFILE <id> IN <instance>`. |
|
|
261
|
+
| `mailstore_run_job` | operator | Confirm `RUN JOB <id> IN <instance>`. |
|
|
262
|
+
| `mailstore_cancel_job` | operator | Confirm `CANCEL JOB <id> IN <instance>`. |
|
|
263
|
+
| `mailstore_verify_store` | operator | Confirm `VERIFY STORE <id> IN <instance>`. |
|
|
264
|
+
| `mailstore_refresh_store_statistics` | operator | Confirm `REFRESH STORE STATISTICS IN <instance>`. |
|
|
265
|
+
| `mailstore_test_smtp` | operator | Confirm `TEST SMTP IN <instance>`. |
|
|
266
|
+
| `mailstore_sync_directory_users` | operator (dry-run) / administrator (apply) | Dry run by default. |
|
|
267
|
+
| `mailstore_create_user` | administrator | Confirm `CREATE USER <userName> IN <instance>`. |
|
|
268
|
+
| `mailstore_update_user` | administrator | Only changes the fields you pass. |
|
|
269
|
+
| `mailstore_set_user_password` | administrator | Password never returned. |
|
|
270
|
+
| `mailstore_delete_user` | administrator + destructive | Confirm `DELETE USER <userName> FROM <instance>`. |
|
|
271
|
+
| `mailstore_verify_all_stores` | administrator + destructive | Expensive; confirm `VERIFY ALL STORES IN <instance>`. |
|
|
272
|
+
| `mailstore_set_retention_policies` | administrator + destructive | Optimistic-concurrency hash guard. |
|
|
273
|
+
| `mailstore_refresh_capabilities` | administrator | Reload API metadata. |
|
|
274
|
+
| `mailstore_invoke_api` | administrator + `MCP_ENABLE_RAW_API` | Allow-listed generic invoke; denylist enforced. |
|
|
275
|
+
|
|
276
|
+
Phase-two tools (instance/store/credential/profile/job lifecycle, store transfer/merge/repair/recovery) are intentionally **not** in the first release. See the specification.
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## Confirmation model
|
|
281
|
+
|
|
282
|
+
State-changing tools require an **exact** confirmation string, generated from the resolved instance and target. Generic words (`yes`, `confirm`, `proceed`) are rejected. Examples:
|
|
283
|
+
|
|
284
|
+
- `STOP customer-a`
|
|
285
|
+
- `DELETE USER jsmith FROM customer-a`
|
|
286
|
+
- `CHANGE RETENTION POLICIES IN customer-a`
|
|
287
|
+
|
|
288
|
+
If you omit or mismatch it, the tool returns `CONFIRMATION_REQUIRED` / `CONFIRMATION_MISMATCH` with the exact string required — nothing is executed. Retry with that string.
|
|
289
|
+
|
|
290
|
+
`mailstore_set_retention_policies` additionally requires `expectedCurrentHash` (from `mailstore_get_compliance`); if the live policies changed since you read them, the change is refused with `CONCURRENT_MODIFICATION`.
|
|
291
|
+
|
|
292
|
+
---
|
|
293
|
+
|
|
294
|
+
## Resources
|
|
295
|
+
|
|
296
|
+
Read-only MCP resources (no credentials exposed):
|
|
297
|
+
|
|
298
|
+
- `mailstore://health` — reachability, auth, TLS, version, access mode
|
|
299
|
+
- `mailstore://environment`
|
|
300
|
+
- `mailstore://service-status`
|
|
301
|
+
- `mailstore://instances`
|
|
302
|
+
- `mailstore://capabilities`
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
## Error model
|
|
307
|
+
|
|
308
|
+
Errors are structured with a stable `code`, a concise `message`, and safe `details` — never secrets, auth headers, or stack traces:
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{ "code": "AMBIGUOUS_INSTANCE", "message": "The instance name matched multiple MailStore instances.", "details": { "matches": [ ... ] } }
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Codes: `CONFIGURATION_ERROR`, `AUTHENTICATION_FAILED`, `AUTHORIZATION_FAILED`, `TLS_ERROR`, `MAILSTORE_UNAVAILABLE`, `MAILSTORE_API_ERROR`, `MAILSTORE_OPERATION_FAILED`, `MAILSTORE_OPERATION_TIMEOUT`, `UNSUPPORTED_FUNCTION`, `INVALID_ARGUMENT`, `INSTANCE_NOT_FOUND`, `AMBIGUOUS_INSTANCE`, `OBJECT_NOT_FOUND`, `CONFIRMATION_REQUIRED`, `CONFIRMATION_MISMATCH`, `ACCESS_MODE_DENIED`, `DESTRUCTIVE_ACTION_DISABLED`, `CONCURRENT_MODIFICATION`, `RESULT_TOO_LARGE`.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Development & testing
|
|
319
|
+
|
|
320
|
+
```bash
|
|
321
|
+
npm install
|
|
322
|
+
npm run build # tsc
|
|
323
|
+
npm run typecheck # tsc --noEmit
|
|
324
|
+
npm run lint # eslint
|
|
325
|
+
npm test # vitest (unit + mock server + in-process MCP)
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Unit tests cover the safety boundaries (form encoding, BOM handling, envelope/error parsing, long-operation polling and timeout, retry policy, metadata & argument validation, instance resolution & ambiguity, confirmations, access-mode gating, secret redaction, output truncation, time-zone parameter spelling). A mock MailStore server exercises the client end-to-end, and an in-process MCP client verifies that read-only mode registers no mutating tools and that confirmations are enforced.
|
|
329
|
+
|
|
330
|
+
### Live integration tests (opt-in, read-only)
|
|
331
|
+
|
|
332
|
+
`tests/integration/live-readonly.test.ts` runs strictly read-only checks against a real server when `MAILSTORE_BASE_URL` is configured (via `.env`). It never mutates. Run with:
|
|
333
|
+
|
|
334
|
+
```bash
|
|
335
|
+
npm run test:integration
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Mutating integration tests are intentionally not included; if you add any, gate them behind `MAILSTORE_MUTATION_TESTS=true` and a dedicated `MAILSTORE_TEST_INSTANCE` — never a production customer instance.
|
|
339
|
+
|
|
340
|
+
> **Note on live metadata vs. published reference:** the live SPE metadata is the source of truth. This server was aligned to it — e.g. `GetProfiles` requires a `raw` argument, `GetWorkerResults` uses `timeZoneID`/`profileID` (capitalised) while `GetJobResults` uses `timeZoneId`/`jobId`, `SetRetentionPolicies` takes a single `config` JSON argument, and user privilege/email/POP3 lists are comma-separated **strings**, not JSON arrays.
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## Troubleshooting
|
|
345
|
+
|
|
346
|
+
| Symptom | Likely cause |
|
|
347
|
+
|---------|--------------|
|
|
348
|
+
| `CONFIGURATION_ERROR` at startup | Missing/invalid env var, or `MAILSTORE_BASE_URL` includes `/api`. |
|
|
349
|
+
| `AUTHENTICATION_FAILED` | Wrong username/password, or MFA account needs an API password. |
|
|
350
|
+
| `TLS_ERROR` | Untrusted certificate — set `MAILSTORE_CA_FILE`, or `MAILSTORE_VERIFY_TLS=false` for a lab only. |
|
|
351
|
+
| Startup aborts: missing essential functions | The account/server lacks core API functions; check API access. |
|
|
352
|
+
| A tool is missing | It requires a higher access mode, the destructive flag, or an API function unavailable on this server. |
|
|
353
|
+
| `AMBIGUOUS_INSTANCE` | The name matches multiple instances — pass the exact instanceID. |
|
|
354
|
+
| SSE drops / hangs behind Caddy | Ensure unbuffered HTTP/1.1 proxying (`flush_interval -1`). |
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## License
|
|
359
|
+
|
|
360
|
+
MIT
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { type AppConfig } from './schema.js';
|
|
2
|
+
/**
|
|
3
|
+
* Thrown when required configuration is missing or invalid. The server must fail
|
|
4
|
+
* closed (never start) rather than run with partial or insecure configuration.
|
|
5
|
+
*/
|
|
6
|
+
export declare class ConfigurationError extends Error {
|
|
7
|
+
readonly name = "ConfigurationError";
|
|
8
|
+
constructor(message: string);
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Load and validate configuration from the process environment. Throws a
|
|
12
|
+
* ConfigurationError (with all issues) on any validation failure.
|
|
13
|
+
*/
|
|
14
|
+
export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { EnvSchema } from './schema.js';
|
|
2
|
+
/**
|
|
3
|
+
* Thrown when required configuration is missing or invalid. The server must fail
|
|
4
|
+
* closed (never start) rather than run with partial or insecure configuration.
|
|
5
|
+
*/
|
|
6
|
+
export class ConfigurationError extends Error {
|
|
7
|
+
name = 'ConfigurationError';
|
|
8
|
+
constructor(message) {
|
|
9
|
+
super(message);
|
|
10
|
+
}
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Load and validate configuration from the process environment. Throws a
|
|
14
|
+
* ConfigurationError (with all issues) on any validation failure.
|
|
15
|
+
*/
|
|
16
|
+
export function loadConfig(env = process.env) {
|
|
17
|
+
const parsed = EnvSchema.safeParse(env);
|
|
18
|
+
if (!parsed.success) {
|
|
19
|
+
const issues = parsed.error.issues
|
|
20
|
+
.map((i) => ` - ${i.path.join('.') || '(root)'}: ${i.message}`)
|
|
21
|
+
.join('\n');
|
|
22
|
+
throw new ConfigurationError(`Invalid configuration:\n${issues}`);
|
|
23
|
+
}
|
|
24
|
+
const e = parsed.data;
|
|
25
|
+
return {
|
|
26
|
+
baseUrl: e.MAILSTORE_BASE_URL,
|
|
27
|
+
username: e.MAILSTORE_USERNAME,
|
|
28
|
+
password: e.MAILSTORE_PASSWORD,
|
|
29
|
+
verifyTls: e.MAILSTORE_VERIFY_TLS,
|
|
30
|
+
caFile: e.MAILSTORE_CA_FILE,
|
|
31
|
+
requestTimeoutMs: e.MAILSTORE_REQUEST_TIMEOUT_MS,
|
|
32
|
+
longPollTimeoutMs: e.MAILSTORE_LONG_POLL_TIMEOUT_MS,
|
|
33
|
+
operationTimeoutMs: e.MAILSTORE_OPERATION_TIMEOUT_MS,
|
|
34
|
+
metadataCacheTtlSeconds: e.MAILSTORE_METADATA_CACHE_TTL_SECONDS,
|
|
35
|
+
instanceCacheTtlSeconds: e.MAILSTORE_INSTANCE_CACHE_TTL_SECONDS,
|
|
36
|
+
accessMode: e.MCP_ACCESS_MODE,
|
|
37
|
+
enableRawApi: e.MCP_ENABLE_RAW_API,
|
|
38
|
+
allowDestructive: e.MCP_ALLOW_DESTRUCTIVE,
|
|
39
|
+
allowBulkInstanceActions: e.MCP_ALLOW_BULK_INSTANCE_ACTIONS,
|
|
40
|
+
maxResultItems: e.MCP_MAX_RESULT_ITEMS,
|
|
41
|
+
logLevel: e.LOG_LEVEL,
|
|
42
|
+
logFormat: e.LOG_FORMAT,
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
//# sourceMappingURL=env.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAkB,MAAM,aAAa,CAAC;AAExD;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,IAAI,GAAG,oBAAoB,CAAC;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;aAC/B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aAC/D,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,kBAAkB,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;IACtB,OAAO;QACL,OAAO,EAAE,CAAC,CAAC,kBAAkB;QAC7B,QAAQ,EAAE,CAAC,CAAC,kBAAkB;QAC9B,QAAQ,EAAE,CAAC,CAAC,kBAAkB;QAC9B,SAAS,EAAE,CAAC,CAAC,oBAAoB;QACjC,MAAM,EAAE,CAAC,CAAC,iBAAiB;QAC3B,gBAAgB,EAAE,CAAC,CAAC,4BAA4B;QAChD,iBAAiB,EAAE,CAAC,CAAC,8BAA8B;QACnD,kBAAkB,EAAE,CAAC,CAAC,8BAA8B;QACpD,uBAAuB,EAAE,CAAC,CAAC,oCAAoC;QAC/D,uBAAuB,EAAE,CAAC,CAAC,oCAAoC;QAC/D,UAAU,EAAE,CAAC,CAAC,eAAe;QAC7B,YAAY,EAAE,CAAC,CAAC,kBAAkB;QAClC,gBAAgB,EAAE,CAAC,CAAC,qBAAqB;QACzC,wBAAwB,EAAE,CAAC,CAAC,+BAA+B;QAC3D,cAAc,EAAE,CAAC,CAAC,oBAAoB;QACtC,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,SAAS,EAAE,CAAC,CAAC,UAAU;KACxB,CAAC;AACJ,CAAC"}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/** MCP access modes, in increasing order of privilege. */
|
|
3
|
+
export declare const ACCESS_MODES: readonly ["read-only", "operator", "administrator"];
|
|
4
|
+
export type AccessMode = (typeof ACCESS_MODES)[number];
|
|
5
|
+
/** Ordered rank for access-mode comparison (higher = more privileged). */
|
|
6
|
+
export declare const ACCESS_MODE_RANK: Record<AccessMode, number>;
|
|
7
|
+
/**
|
|
8
|
+
* Environment configuration schema. Every value comes from process.env (or a
|
|
9
|
+
* Docker secret injected into the environment). Defaults mirror .env.example.
|
|
10
|
+
*/
|
|
11
|
+
export declare const EnvSchema: z.ZodObject<{
|
|
12
|
+
MAILSTORE_BASE_URL: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
|
|
13
|
+
MAILSTORE_USERNAME: z.ZodString;
|
|
14
|
+
MAILSTORE_PASSWORD: z.ZodString;
|
|
15
|
+
MAILSTORE_VERIFY_TLS: z.ZodDefault<z.ZodEffects<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEnum<["true", "false", "1", "0", "yes", "no"]>>, boolean, string>>;
|
|
16
|
+
MAILSTORE_CA_FILE: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>;
|
|
17
|
+
MAILSTORE_REQUEST_TIMEOUT_MS: z.ZodDefault<z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>>;
|
|
18
|
+
MAILSTORE_LONG_POLL_TIMEOUT_MS: z.ZodDefault<z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>>;
|
|
19
|
+
MAILSTORE_OPERATION_TIMEOUT_MS: z.ZodDefault<z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>>;
|
|
20
|
+
MAILSTORE_METADATA_CACHE_TTL_SECONDS: z.ZodDefault<z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>>;
|
|
21
|
+
MAILSTORE_INSTANCE_CACHE_TTL_SECONDS: z.ZodDefault<z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>>;
|
|
22
|
+
MCP_ACCESS_MODE: z.ZodDefault<z.ZodEnum<["read-only", "operator", "administrator"]>>;
|
|
23
|
+
MCP_ENABLE_RAW_API: z.ZodDefault<z.ZodEffects<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEnum<["true", "false", "1", "0", "yes", "no"]>>, boolean, string>>;
|
|
24
|
+
MCP_ALLOW_DESTRUCTIVE: z.ZodDefault<z.ZodEffects<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEnum<["true", "false", "1", "0", "yes", "no"]>>, boolean, string>>;
|
|
25
|
+
MCP_ALLOW_BULK_INSTANCE_ACTIONS: z.ZodDefault<z.ZodEffects<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEnum<["true", "false", "1", "0", "yes", "no"]>>, boolean, string>>;
|
|
26
|
+
MCP_MAX_RESULT_ITEMS: z.ZodDefault<z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>>;
|
|
27
|
+
LOG_LEVEL: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
|
|
28
|
+
LOG_FORMAT: z.ZodDefault<z.ZodEnum<["json", "pretty"]>>;
|
|
29
|
+
}, "strip", z.ZodTypeAny, {
|
|
30
|
+
MAILSTORE_BASE_URL: string;
|
|
31
|
+
MAILSTORE_USERNAME: string;
|
|
32
|
+
MAILSTORE_PASSWORD: string;
|
|
33
|
+
MAILSTORE_VERIFY_TLS: boolean;
|
|
34
|
+
MAILSTORE_REQUEST_TIMEOUT_MS: number;
|
|
35
|
+
MAILSTORE_LONG_POLL_TIMEOUT_MS: number;
|
|
36
|
+
MAILSTORE_OPERATION_TIMEOUT_MS: number;
|
|
37
|
+
MAILSTORE_METADATA_CACHE_TTL_SECONDS: number;
|
|
38
|
+
MAILSTORE_INSTANCE_CACHE_TTL_SECONDS: number;
|
|
39
|
+
MCP_ACCESS_MODE: "read-only" | "operator" | "administrator";
|
|
40
|
+
MCP_ENABLE_RAW_API: boolean;
|
|
41
|
+
MCP_ALLOW_DESTRUCTIVE: boolean;
|
|
42
|
+
MCP_ALLOW_BULK_INSTANCE_ACTIONS: boolean;
|
|
43
|
+
MCP_MAX_RESULT_ITEMS: number;
|
|
44
|
+
LOG_LEVEL: "debug" | "info" | "warn" | "error";
|
|
45
|
+
LOG_FORMAT: "json" | "pretty";
|
|
46
|
+
MAILSTORE_CA_FILE?: string | undefined;
|
|
47
|
+
}, {
|
|
48
|
+
MAILSTORE_BASE_URL: string;
|
|
49
|
+
MAILSTORE_USERNAME: string;
|
|
50
|
+
MAILSTORE_PASSWORD: string;
|
|
51
|
+
MAILSTORE_VERIFY_TLS?: string | undefined;
|
|
52
|
+
MAILSTORE_CA_FILE?: string | undefined;
|
|
53
|
+
MAILSTORE_REQUEST_TIMEOUT_MS?: string | undefined;
|
|
54
|
+
MAILSTORE_LONG_POLL_TIMEOUT_MS?: string | undefined;
|
|
55
|
+
MAILSTORE_OPERATION_TIMEOUT_MS?: string | undefined;
|
|
56
|
+
MAILSTORE_METADATA_CACHE_TTL_SECONDS?: string | undefined;
|
|
57
|
+
MAILSTORE_INSTANCE_CACHE_TTL_SECONDS?: string | undefined;
|
|
58
|
+
MCP_ACCESS_MODE?: "read-only" | "operator" | "administrator" | undefined;
|
|
59
|
+
MCP_ENABLE_RAW_API?: string | undefined;
|
|
60
|
+
MCP_ALLOW_DESTRUCTIVE?: string | undefined;
|
|
61
|
+
MCP_ALLOW_BULK_INSTANCE_ACTIONS?: string | undefined;
|
|
62
|
+
MCP_MAX_RESULT_ITEMS?: string | undefined;
|
|
63
|
+
LOG_LEVEL?: "debug" | "info" | "warn" | "error" | undefined;
|
|
64
|
+
LOG_FORMAT?: "json" | "pretty" | undefined;
|
|
65
|
+
}>;
|
|
66
|
+
export type Env = z.infer<typeof EnvSchema>;
|
|
67
|
+
/** Application configuration derived from the environment. */
|
|
68
|
+
export interface AppConfig {
|
|
69
|
+
baseUrl: string;
|
|
70
|
+
username: string;
|
|
71
|
+
password: string;
|
|
72
|
+
verifyTls: boolean;
|
|
73
|
+
caFile: string | undefined;
|
|
74
|
+
requestTimeoutMs: number;
|
|
75
|
+
longPollTimeoutMs: number;
|
|
76
|
+
operationTimeoutMs: number;
|
|
77
|
+
metadataCacheTtlSeconds: number;
|
|
78
|
+
instanceCacheTtlSeconds: number;
|
|
79
|
+
accessMode: AccessMode;
|
|
80
|
+
enableRawApi: boolean;
|
|
81
|
+
allowDestructive: boolean;
|
|
82
|
+
allowBulkInstanceActions: boolean;
|
|
83
|
+
maxResultItems: number;
|
|
84
|
+
logLevel: 'debug' | 'info' | 'warn' | 'error';
|
|
85
|
+
logFormat: 'json' | 'pretty';
|
|
86
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/** MCP access modes, in increasing order of privilege. */
|
|
3
|
+
export const ACCESS_MODES = ['read-only', 'operator', 'administrator'];
|
|
4
|
+
/** Ordered rank for access-mode comparison (higher = more privileged). */
|
|
5
|
+
export const ACCESS_MODE_RANK = {
|
|
6
|
+
'read-only': 0,
|
|
7
|
+
operator: 1,
|
|
8
|
+
administrator: 2,
|
|
9
|
+
};
|
|
10
|
+
const boolFromEnv = z
|
|
11
|
+
.string()
|
|
12
|
+
.transform((v) => v.trim().toLowerCase())
|
|
13
|
+
.pipe(z.enum(['true', 'false', '1', '0', 'yes', 'no']))
|
|
14
|
+
.transform((v) => v === 'true' || v === '1' || v === 'yes');
|
|
15
|
+
const intFromEnv = (min, max) => z
|
|
16
|
+
.string()
|
|
17
|
+
.transform((v) => Number(v))
|
|
18
|
+
.pipe(z.number().int().min(min).max(max));
|
|
19
|
+
/**
|
|
20
|
+
* Environment configuration schema. Every value comes from process.env (or a
|
|
21
|
+
* Docker secret injected into the environment). Defaults mirror .env.example.
|
|
22
|
+
*/
|
|
23
|
+
export const EnvSchema = z.object({
|
|
24
|
+
// Connection
|
|
25
|
+
MAILSTORE_BASE_URL: z
|
|
26
|
+
.string()
|
|
27
|
+
.url('MAILSTORE_BASE_URL must be a valid URL')
|
|
28
|
+
.refine((u) => u.startsWith('https://'), 'MAILSTORE_BASE_URL must use HTTPS')
|
|
29
|
+
.refine((u) => !/\/api\/?$/i.test(u), 'MAILSTORE_BASE_URL must not include the /api path')
|
|
30
|
+
.transform((u) => u.replace(/\/+$/, '')),
|
|
31
|
+
MAILSTORE_USERNAME: z.string().min(1, 'MAILSTORE_USERNAME is required'),
|
|
32
|
+
MAILSTORE_PASSWORD: z.string().min(1, 'MAILSTORE_PASSWORD is required'),
|
|
33
|
+
// TLS
|
|
34
|
+
MAILSTORE_VERIFY_TLS: boolFromEnv.default('true'),
|
|
35
|
+
MAILSTORE_CA_FILE: z
|
|
36
|
+
.string()
|
|
37
|
+
.optional()
|
|
38
|
+
.transform((v) => (v && v.trim().length > 0 ? v.trim() : undefined)),
|
|
39
|
+
// Timeouts & caching
|
|
40
|
+
MAILSTORE_REQUEST_TIMEOUT_MS: intFromEnv(1000, 600000).default('30000'),
|
|
41
|
+
MAILSTORE_LONG_POLL_TIMEOUT_MS: intFromEnv(1000, 120000).default('25000'),
|
|
42
|
+
MAILSTORE_OPERATION_TIMEOUT_MS: intFromEnv(1000, 7200000).default('1800000'),
|
|
43
|
+
MAILSTORE_METADATA_CACHE_TTL_SECONDS: intFromEnv(0, 86400).default('3600'),
|
|
44
|
+
MAILSTORE_INSTANCE_CACHE_TTL_SECONDS: intFromEnv(0, 3600).default('60'),
|
|
45
|
+
// MCP behaviour & safety
|
|
46
|
+
MCP_ACCESS_MODE: z.enum(ACCESS_MODES).default('read-only'),
|
|
47
|
+
MCP_ENABLE_RAW_API: boolFromEnv.default('false'),
|
|
48
|
+
MCP_ALLOW_DESTRUCTIVE: boolFromEnv.default('false'),
|
|
49
|
+
MCP_ALLOW_BULK_INSTANCE_ACTIONS: boolFromEnv.default('false'),
|
|
50
|
+
MCP_MAX_RESULT_ITEMS: intFromEnv(1, 10000).default('200'),
|
|
51
|
+
// Logging
|
|
52
|
+
LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
|
|
53
|
+
LOG_FORMAT: z.enum(['json', 'pretty']).default('json'),
|
|
54
|
+
});
|
|
55
|
+
//# sourceMappingURL=schema.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"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"}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
3
|
+
import { loadConfig, ConfigurationError } from './config/env.js';
|
|
4
|
+
import { initLogger, getLogger } from './logging/logger.js';
|
|
5
|
+
import { buildServer } from './server.js';
|
|
6
|
+
async function main() {
|
|
7
|
+
// 1. Configuration (fail closed on any error).
|
|
8
|
+
const config = loadConfig();
|
|
9
|
+
// 2. Logging to stderr (stdout is reserved for the MCP protocol).
|
|
10
|
+
const logger = initLogger({ level: config.logLevel, format: config.logFormat });
|
|
11
|
+
logger.info({
|
|
12
|
+
component: 'startup',
|
|
13
|
+
baseUrl: config.baseUrl,
|
|
14
|
+
accessMode: config.accessMode,
|
|
15
|
+
verifyTls: config.verifyTls,
|
|
16
|
+
enableRawApi: config.enableRawApi,
|
|
17
|
+
allowDestructive: config.allowDestructive,
|
|
18
|
+
}, 'starting MailStore SPE MCP server');
|
|
19
|
+
if (!config.verifyTls) {
|
|
20
|
+
logger.warn({ component: 'startup' }, '⚠️ TLS certificate verification is DISABLED (MAILSTORE_VERIFY_TLS=false). This is insecure and intended for lab use only.');
|
|
21
|
+
}
|
|
22
|
+
// 3. Build server (loads metadata, validates capabilities, registers tools).
|
|
23
|
+
const built = await buildServer(config, logger);
|
|
24
|
+
logger.info({
|
|
25
|
+
component: 'startup',
|
|
26
|
+
registeredTools: built.registration.registered,
|
|
27
|
+
skippedByMode: built.registration.skippedByMode.length,
|
|
28
|
+
skippedByCapability: built.registration.skippedByCapability.length,
|
|
29
|
+
}, 'server built');
|
|
30
|
+
// 4. Connect stdio transport.
|
|
31
|
+
const transport = new StdioServerTransport();
|
|
32
|
+
await built.server.connect(transport);
|
|
33
|
+
logger.info({ component: 'startup' }, 'MailStore SPE MCP server running on stdio');
|
|
34
|
+
// 5. Graceful shutdown.
|
|
35
|
+
const shutdown = (signal) => {
|
|
36
|
+
logger.info({ component: 'shutdown', signal }, 'shutting down');
|
|
37
|
+
void built
|
|
38
|
+
.close()
|
|
39
|
+
.catch((err) => logger.error({ component: 'shutdown', err: err.message }, 'error during shutdown'))
|
|
40
|
+
.finally(() => process.exit(0));
|
|
41
|
+
};
|
|
42
|
+
process.on('SIGTERM', () => shutdown('SIGTERM'));
|
|
43
|
+
process.on('SIGINT', () => shutdown('SIGINT'));
|
|
44
|
+
}
|
|
45
|
+
main().catch((err) => {
|
|
46
|
+
// Use the logger if available; otherwise write a minimal message to stderr.
|
|
47
|
+
if (err instanceof ConfigurationError) {
|
|
48
|
+
process.stderr.write(`Configuration error:\n${err.message}\n`);
|
|
49
|
+
}
|
|
50
|
+
else {
|
|
51
|
+
try {
|
|
52
|
+
getLogger().error({ component: 'fatal', err: err.message }, 'fatal error during startup');
|
|
53
|
+
}
|
|
54
|
+
catch {
|
|
55
|
+
process.stderr.write(`Fatal: ${err?.message ?? String(err)}\n`);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
process.exit(1);
|
|
59
|
+
});
|
|
60
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { type Logger } from 'pino';
|
|
2
|
+
/**
|
|
3
|
+
* Structured logger built on Pino, writing to stderr (fd 2) so that stdout
|
|
4
|
+
* carries only MCP protocol messages. Secret-like keys are redacted by Pino's
|
|
5
|
+
* built-in redaction plus a custom serializer for arbitrary nested payloads.
|
|
6
|
+
*/
|
|
7
|
+
export interface LoggerOptions {
|
|
8
|
+
level: 'debug' | 'info' | 'warn' | 'error';
|
|
9
|
+
format: 'json' | 'pretty';
|
|
10
|
+
}
|
|
11
|
+
export declare function initLogger(opts: LoggerOptions): Logger;
|
|
12
|
+
export declare function getLogger(): Logger;
|