@teamnetwork-nz/smtp-mcp-server 1.4.1 → 1.4.3
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 +43 -17
- package/README.md +51 -0
- package/dist/config.js +16 -16
- package/dist/index.js +14 -14
- package/dist/strict-tools.js +3 -3
- package/package.json +8 -7
package/.env.example
CHANGED
|
@@ -1,18 +1,44 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
SMTP_SECURE=false # set to "true" for port 465 implicit TLS
|
|
5
|
-
SMTP_IGNORE_TLS=false # set to "true" for plain SMTP with no TLS (e.g. port 25 internal relay)
|
|
6
|
-
SMTP_USER=user@example.com # optional — omit for unauthenticated relays
|
|
7
|
-
SMTP_PASS=your-password-here # optional — omit for unauthenticated relays
|
|
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.
|
|
8
4
|
|
|
9
|
-
#
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
#
|
|
14
|
-
#
|
|
15
|
-
#
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
5
|
+
# Compatibility alias for SMTP_ALLOWED_ADDRESSES; canonical variable wins.
|
|
6
|
+
# ALLOWED_ADDRESSES=<set-privately>
|
|
7
|
+
# Compatibility alias for SMTP_ALLOWED_DOMAINS; canonical variable wins.
|
|
8
|
+
# ALLOWED_DOMAINS=<set-privately>
|
|
9
|
+
# Comma-separated valid recipient addresses; one allowlist is required when SMTP_READWRITE=true.
|
|
10
|
+
# SMTP_ALLOWED_ADDRESSES=<set-privately>
|
|
11
|
+
# Comma-separated recipient domains; one allowlist is required when SMTP_READWRITE=true.
|
|
12
|
+
# SMTP_ALLOWED_DOMAINS=<set-privately>
|
|
13
|
+
# Valid sender email address; supply privately.
|
|
14
|
+
SMTP_FROM_ADDRESS=<set-privately>
|
|
15
|
+
# Sender display name.
|
|
16
|
+
# SMTP_FROM_NAME=<set-privately>
|
|
17
|
+
# SMTP relay hostname.
|
|
18
|
+
SMTP_HOST=<set-privately>
|
|
19
|
+
# Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener.
|
|
20
|
+
# SMTP_HTTP_ALLOWED_HOSTS=<set-privately>
|
|
21
|
+
# Comma-separated browser Origin allowlist; configure when browser clients need access.
|
|
22
|
+
# SMTP_HTTP_ALLOWED_ORIGINS=<set-privately>
|
|
23
|
+
# Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>.
|
|
24
|
+
# SMTP_HTTP_BEARER_TOKEN=<set-privately>
|
|
25
|
+
# Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts.
|
|
26
|
+
# SMTP_HTTP_HOST=127.0.0.1
|
|
27
|
+
# Maximum HTTP request body; integer 1–16777216 bytes.
|
|
28
|
+
# SMTP_HTTP_MAX_BODY_BYTES=1048576
|
|
29
|
+
# HTTP listener port; integer 1–65535.
|
|
30
|
+
# SMTP_HTTP_PORT=3000
|
|
31
|
+
# true disables STARTTLS; leave false for normal use.
|
|
32
|
+
# SMTP_IGNORE_TLS=false
|
|
33
|
+
# SMTP password when the relay requires authentication.
|
|
34
|
+
# SMTP_PASS=<set-privately>
|
|
35
|
+
# SMTP relay TCP port; integer 1–65535.
|
|
36
|
+
# SMTP_PORT=587
|
|
37
|
+
# Only true enables mutation tools; read-only is the default. Review each operation before use.
|
|
38
|
+
# SMTP_READWRITE=false
|
|
39
|
+
# true uses implicit TLS, usually port 465; false allows STARTTLS.
|
|
40
|
+
# SMTP_SECURE=false
|
|
41
|
+
# stdio or http; HTTP serves /mcp and GET /health.
|
|
42
|
+
# SMTP_TRANSPORT=stdio
|
|
43
|
+
# SMTP username when the relay requires authentication.
|
|
44
|
+
# SMTP_USER=<set-privately>
|
package/README.md
CHANGED
|
@@ -167,3 +167,54 @@ scoop install mailpit && mailpit
|
|
|
167
167
|
```
|
|
168
168
|
|
|
169
169
|
Set `SMTP_HOST=localhost`, `SMTP_PORT=1025`, omit `SMTP_USER`/`SMTP_PASS`. View caught emails at http://localhost:8025.
|
|
170
|
+
|
|
171
|
+
<!-- BEGIN MCP configuration reference -->
|
|
172
|
+
## Environment variable reference
|
|
173
|
+
|
|
174
|
+
The server automatically loads `.env` from its working directory; environment variables already set by the client take precedence.
|
|
175
|
+
|
|
176
|
+
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.
|
|
177
|
+
|
|
178
|
+
| Variable | Required | Default | Purpose and accepted values |
|
|
179
|
+
|---|---|---|---|
|
|
180
|
+
| `ALLOWED_ADDRESSES` | Deprecated | `unset` | Compatibility alias for SMTP_ALLOWED_ADDRESSES; canonical variable wins. |
|
|
181
|
+
| `ALLOWED_DOMAINS` | Deprecated | `unset` | Compatibility alias for SMTP_ALLOWED_DOMAINS; canonical variable wins. |
|
|
182
|
+
| `SMTP_ALLOWED_ADDRESSES` | Conditional | `unset` | Comma-separated valid recipient addresses; one allowlist is required when SMTP_READWRITE=true. |
|
|
183
|
+
| `SMTP_ALLOWED_DOMAINS` | Conditional | `unset` | Comma-separated recipient domains; one allowlist is required when SMTP_READWRITE=true. |
|
|
184
|
+
| `SMTP_FROM_ADDRESS` | Yes | `unset` | Valid sender email address; supply privately. |
|
|
185
|
+
| `SMTP_FROM_NAME` | No | `sender address` | Sender display name. |
|
|
186
|
+
| `SMTP_HOST` | Yes | `unset` | SMTP relay hostname. |
|
|
187
|
+
| `SMTP_HTTP_ALLOWED_HOSTS` | Conditional | `unset` | Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener. |
|
|
188
|
+
| `SMTP_HTTP_ALLOWED_ORIGINS` | No | `unset` | Comma-separated browser Origin allowlist; configure when browser clients need access. |
|
|
189
|
+
| `SMTP_HTTP_BEARER_TOKEN` | Conditional | `unset` | Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>. |
|
|
190
|
+
| `SMTP_HTTP_HOST` | No | `127.0.0.1` | Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts. |
|
|
191
|
+
| `SMTP_HTTP_MAX_BODY_BYTES` | No | `1048576` | Maximum HTTP request body; integer 1–16777216 bytes. |
|
|
192
|
+
| `SMTP_HTTP_PORT` | No | `3000` | HTTP listener port; integer 1–65535. |
|
|
193
|
+
| `SMTP_IGNORE_TLS` | No | `false` | true disables STARTTLS; leave false for normal use. |
|
|
194
|
+
| `SMTP_PASS` | Conditional | `unset` | SMTP password when the relay requires authentication. |
|
|
195
|
+
| `SMTP_PORT` | No | `587` | SMTP relay TCP port; integer 1–65535. |
|
|
196
|
+
| `SMTP_READWRITE` | No | `false` | Only true enables mutation tools; read-only is the default. Review each operation before use. |
|
|
197
|
+
| `SMTP_SECURE` | No | `false` | true uses implicit TLS, usually port 465; false allows STARTTLS. |
|
|
198
|
+
| `SMTP_TRANSPORT` | No | `stdio` | stdio or http; HTTP serves /mcp and GET /health. |
|
|
199
|
+
| `SMTP_USER` | Conditional | `unset` | SMTP username when the relay requires authentication. |
|
|
200
|
+
|
|
201
|
+
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.
|
|
202
|
+
|
|
203
|
+
### Agent first-use workflow
|
|
204
|
+
|
|
205
|
+
Inspect the usage resource and active sender/recipient restrictions first. Sending requires SMTP_READWRITE=true and a recipient allowlist. Verify recipients, body and attachments before invoking the send tool.
|
|
206
|
+
|
|
207
|
+
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.
|
|
208
|
+
|
|
209
|
+
### Repository and package privacy
|
|
210
|
+
|
|
211
|
+
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.
|
|
212
|
+
<!-- END MCP configuration reference -->
|
|
213
|
+
|
|
214
|
+
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.
|
|
215
|
+
|
|
216
|
+
### Development and diagnostics
|
|
217
|
+
|
|
218
|
+
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.
|
|
219
|
+
|
|
220
|
+
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/dist/config.js
CHANGED
|
@@ -5,25 +5,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
6
|
exports.config = void 0;
|
|
7
7
|
const dotenv_1 = __importDefault(require("dotenv"));
|
|
8
|
-
const
|
|
8
|
+
const v3_1 = require("zod/v3");
|
|
9
9
|
dotenv_1.default.config({ quiet: true });
|
|
10
|
-
const configSchema =
|
|
11
|
-
readWrite:
|
|
12
|
-
smtp:
|
|
13
|
-
host:
|
|
14
|
-
port:
|
|
15
|
-
secure:
|
|
16
|
-
ignoreTls:
|
|
17
|
-
user:
|
|
18
|
-
pass:
|
|
10
|
+
const configSchema = v3_1.z.object({
|
|
11
|
+
readWrite: v3_1.z.boolean().default(false),
|
|
12
|
+
smtp: v3_1.z.object({
|
|
13
|
+
host: v3_1.z.string().min(1, "SMTP_HOST is required"),
|
|
14
|
+
port: v3_1.z.coerce.number().int().min(1).max(65535).default(587),
|
|
15
|
+
secure: v3_1.z.boolean().default(false),
|
|
16
|
+
ignoreTls: v3_1.z.boolean().default(false),
|
|
17
|
+
user: v3_1.z.string().min(1).optional(),
|
|
18
|
+
pass: v3_1.z.string().min(1).optional(),
|
|
19
19
|
}),
|
|
20
|
-
from:
|
|
21
|
-
address:
|
|
22
|
-
name:
|
|
20
|
+
from: v3_1.z.object({
|
|
21
|
+
address: v3_1.z.string().email("SMTP_FROM_ADDRESS must be a valid email"),
|
|
22
|
+
name: v3_1.z.string().optional(),
|
|
23
23
|
}),
|
|
24
|
-
restrictions:
|
|
25
|
-
allowedDomains:
|
|
26
|
-
allowedAddresses:
|
|
24
|
+
restrictions: v3_1.z.object({
|
|
25
|
+
allowedDomains: v3_1.z.array(v3_1.z.string()).default([]),
|
|
26
|
+
allowedAddresses: v3_1.z.array(v3_1.z.string().email()).default([]),
|
|
27
27
|
}),
|
|
28
28
|
});
|
|
29
29
|
function parseList(value) {
|
package/dist/index.js
CHANGED
|
@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
36
36
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
37
37
|
const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
|
|
38
38
|
const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
|
|
39
|
-
const
|
|
39
|
+
const v3_1 = require("zod/v3");
|
|
40
40
|
const config_js_1 = require("./config.js");
|
|
41
41
|
const restrictions_js_1 = require("./restrictions.js");
|
|
42
42
|
const email_js_1 = require("./email.js");
|
|
@@ -54,12 +54,12 @@ function createConfiguredServer() {
|
|
|
54
54
|
// ---------------------------------------------------------------------------
|
|
55
55
|
// Shared schemas
|
|
56
56
|
// ---------------------------------------------------------------------------
|
|
57
|
-
const attachmentSchema =
|
|
57
|
+
const attachmentSchema = v3_1.z
|
|
58
58
|
.object({
|
|
59
|
-
path:
|
|
60
|
-
filename:
|
|
61
|
-
content:
|
|
62
|
-
content_type:
|
|
59
|
+
path: v3_1.z.string().optional().describe("Absolute path to the file on disk — server reads and encodes it"),
|
|
60
|
+
filename: v3_1.z.string().optional().describe("Override the filename shown to the recipient"),
|
|
61
|
+
content: v3_1.z.string().optional().describe("Base64-encoded file content (use path instead where possible)"),
|
|
62
|
+
content_type: v3_1.z.string().optional().describe("MIME type — auto-detected from path extension if omitted"),
|
|
63
63
|
})
|
|
64
64
|
.refine((a) => a.path || a.content, {
|
|
65
65
|
message: "Each attachment must include either 'path' (preferred) or 'content' (base64)",
|
|
@@ -67,8 +67,8 @@ function createConfiguredServer() {
|
|
|
67
67
|
.refine((a) => !a.content || (a.filename && a.content_type), {
|
|
68
68
|
message: "Attachments using 'content' must also include 'filename' and 'content_type'",
|
|
69
69
|
});
|
|
70
|
-
const recipientSchema =
|
|
71
|
-
.union([
|
|
70
|
+
const recipientSchema = v3_1.z
|
|
71
|
+
.union([v3_1.z.string().email(), v3_1.z.array(v3_1.z.string().email()).min(1)])
|
|
72
72
|
.transform((v) => (Array.isArray(v) ? v : [v]));
|
|
73
73
|
// ---------------------------------------------------------------------------
|
|
74
74
|
// Tool: health
|
|
@@ -125,8 +125,8 @@ function createConfiguredServer() {
|
|
|
125
125
|
"the server will encode the file itself without passing binary data through the agent. " +
|
|
126
126
|
"Use encode_file only when you need to inspect or transform the content before sending.",
|
|
127
127
|
inputSchema: {
|
|
128
|
-
path:
|
|
129
|
-
content_type:
|
|
128
|
+
path: v3_1.z.string().min(1).describe("Absolute or relative path to the file"),
|
|
129
|
+
content_type: v3_1.z
|
|
130
130
|
.string()
|
|
131
131
|
.optional()
|
|
132
132
|
.describe("MIME type override. If omitted the type is detected from the file extension."),
|
|
@@ -170,9 +170,9 @@ function createConfiguredServer() {
|
|
|
170
170
|
description: "Send an email via SMTP. Recipient addresses are validated against the server's allowed domains/addresses policy.",
|
|
171
171
|
inputSchema: {
|
|
172
172
|
to: recipientSchema.describe("Recipient address or list of addresses"),
|
|
173
|
-
subject:
|
|
174
|
-
body:
|
|
175
|
-
body_type:
|
|
173
|
+
subject: v3_1.z.string().min(1).describe("Email subject line"),
|
|
174
|
+
body: v3_1.z.string().min(1).describe("Email body content"),
|
|
175
|
+
body_type: v3_1.z
|
|
176
176
|
.enum(["text", "html"])
|
|
177
177
|
.default("text")
|
|
178
178
|
.describe("Body format — plain text (default) or HTML"),
|
|
@@ -182,7 +182,7 @@ function createConfiguredServer() {
|
|
|
182
182
|
bcc: recipientSchema
|
|
183
183
|
.optional()
|
|
184
184
|
.describe("BCC address or list of addresses"),
|
|
185
|
-
attachments:
|
|
185
|
+
attachments: v3_1.z
|
|
186
186
|
.array(attachmentSchema)
|
|
187
187
|
.optional()
|
|
188
188
|
.describe("Files to attach"),
|
package/dist/strict-tools.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.enforceStrictToolInputs = enforceStrictToolInputs;
|
|
4
|
-
const
|
|
4
|
+
const v3_1 = require("zod/v3");
|
|
5
5
|
function isSchema(value) {
|
|
6
6
|
return typeof value === "object" && value !== null && "_def" in value;
|
|
7
7
|
}
|
|
@@ -13,9 +13,9 @@ function isRawShape(value) {
|
|
|
13
13
|
}
|
|
14
14
|
function strictSchema(schema) {
|
|
15
15
|
if (schema === undefined)
|
|
16
|
-
return
|
|
16
|
+
return v3_1.z.object({}).strict();
|
|
17
17
|
if (isRawShape(schema))
|
|
18
|
-
return
|
|
18
|
+
return v3_1.z.object(schema).strict();
|
|
19
19
|
if (isSchema(schema) && typeof schema.strict === "function")
|
|
20
20
|
return schema.strict();
|
|
21
21
|
return schema;
|
package/package.json
CHANGED
|
@@ -1,22 +1,24 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@teamnetwork-nz/smtp-mcp-server",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.3",
|
|
4
4
|
"description": "MCP server for sending email via SMTP relay",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"bin": {
|
|
7
7
|
"smtp-mcp-server": "dist/index.js"
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
|
-
"dist",
|
|
10
|
+
"dist/**/*.js",
|
|
11
|
+
"dist/**/*.d.ts",
|
|
11
12
|
"README.md",
|
|
12
13
|
".env.example"
|
|
13
14
|
],
|
|
14
15
|
"scripts": {
|
|
15
16
|
"build": "tsc",
|
|
16
|
-
"test": "npm run build && node --test tests/*.test.mjs",
|
|
17
|
+
"test": "npm run build && node --test debug/tests/*.test.mjs",
|
|
17
18
|
"start": "node dist/index.js",
|
|
18
19
|
"dev": "tsc --watch",
|
|
19
|
-
"prepublishOnly": "npm run build"
|
|
20
|
+
"prepublishOnly": "npm run build && npm run audit:package",
|
|
21
|
+
"audit:package": "node scripts/check-package-privacy.mjs"
|
|
20
22
|
},
|
|
21
23
|
"keywords": [
|
|
22
24
|
"mcp",
|
|
@@ -25,7 +27,6 @@
|
|
|
25
27
|
"model-context-protocol",
|
|
26
28
|
"claude"
|
|
27
29
|
],
|
|
28
|
-
"author": "",
|
|
29
30
|
"license": "ISC",
|
|
30
31
|
"type": "commonjs",
|
|
31
32
|
"engines": {
|
|
@@ -35,10 +36,10 @@
|
|
|
35
36
|
"access": "public"
|
|
36
37
|
},
|
|
37
38
|
"dependencies": {
|
|
38
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
39
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
39
40
|
"dotenv": "^17.4.2",
|
|
40
41
|
"nodemailer": "^8.0.7",
|
|
41
|
-
"zod": "^
|
|
42
|
+
"zod": "^4.6.7"
|
|
42
43
|
},
|
|
43
44
|
"devDependencies": {
|
|
44
45
|
"@types/node": "^25.7.0",
|