@teamnetwork-nz/smtp-mcp-server 1.0.0 → 1.1.2

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 CHANGED
@@ -2,6 +2,7 @@
2
2
  SMTP_HOST=smtp.example.com
3
3
  SMTP_PORT=587
4
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)
5
6
  SMTP_USER=user@example.com # optional — omit for unauthenticated relays
6
7
  SMTP_PASS=your-password-here # optional — omit for unauthenticated relays
7
8
 
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @teamnetwork-nz/smtp-mcp-server
2
2
 
3
- An MCP server that lets AI agents send email via any SMTP relay. Recipient restrictions are enforced server-side — an agent cannot bypass them.
3
+ An MCP server that lets AI agents send email via any SMTP relay. Recipient restrictions, sender identity, and SMTP credentials are all enforced server-side — an agent cannot override them.
4
4
 
5
5
  ## Features
6
6
 
@@ -10,6 +10,8 @@ An MCP server that lets AI agents send email via any SMTP relay. Recipient restr
10
10
  - Restrict recipients to allowed domains and/or explicit addresses
11
11
  - Configurable sender name and address
12
12
  - Works with any SMTP server (Gmail, SendGrid, Mailgun, self-hosted, unauthenticated relay, etc.)
13
+ - `health` tool for live connection testing
14
+ - Built-in usage resource agents can read to understand available options
13
15
 
14
16
  ## Install
15
17
 
@@ -17,7 +19,7 @@ An MCP server that lets AI agents send email via any SMTP relay. Recipient restr
17
19
  npm install -g @teamnetwork-nz/smtp-mcp-server
18
20
  ```
19
21
 
20
- Or run directly with npx (no install needed):
22
+ Or run directly with npx (no global install needed):
21
23
 
22
24
  ```bash
23
25
  npx @teamnetwork-nz/smtp-mcp-server
@@ -39,7 +41,8 @@ All configuration is via environment variables (loaded from `.env` if present).
39
41
  |---|---|---|
40
42
  | `SMTP_HOST` | yes | SMTP relay hostname |
41
43
  | `SMTP_PORT` | no | Port — default `587` |
42
- | `SMTP_SECURE` | no | `"true"` for port 465 implicit TLS; default STARTTLS |
44
+ | `SMTP_SECURE` | no | `"true"` for port 465 implicit TLS; otherwise STARTTLS |
45
+ | `SMTP_IGNORE_TLS` | no | `"true"` to disable TLS entirely — plain SMTP, e.g. port 25 internal relay |
43
46
  | `SMTP_USER` | no | SMTP auth username — omit for unauthenticated relays |
44
47
  | `SMTP_PASS` | no | SMTP auth password — omit for unauthenticated relays |
45
48
  | `SMTP_FROM_ADDRESS` | yes | Envelope From address |
@@ -47,7 +50,7 @@ All configuration is via environment variables (loaded from `.env` if present).
47
50
  | `ALLOWED_DOMAINS` | no | Comma-separated domains, e.g. `acme.com,partner.org` |
48
51
  | `ALLOWED_ADDRESSES` | no | Comma-separated explicit addresses |
49
52
 
50
- **Restriction logic:** a recipient is permitted if its domain matches `ALLOWED_DOMAINS` **or** it appears in `ALLOWED_ADDRESSES`. If neither is set, all addresses are permitted — not recommended for production.
53
+ **Restriction logic:** a recipient is permitted if its domain matches `ALLOWED_DOMAINS` **or** it appears in `ALLOWED_ADDRESSES`. All addresses across `to`, `cc`, and `bcc` are checked — a single blocked address rejects the whole request. If neither variable is set, all addresses are permitted (not recommended for production).
51
54
 
52
55
  ## Claude Code Integration
53
56
 
@@ -75,7 +78,28 @@ Add to your `.claude/mcp_config.json` (or `claude_desktop_config.json`):
75
78
 
76
79
  For an unauthenticated internal relay, omit `SMTP_USER` and `SMTP_PASS`.
77
80
 
78
- ## Tool: `send_email`
81
+ ---
82
+
83
+ ## Tools
84
+
85
+ ### `health`
86
+
87
+ No parameters. Performs a live TCP+SMTP handshake against the configured server and returns the active configuration summary.
88
+
89
+ ```
90
+ connection: OK (42 ms)
91
+ smtp_host: smtp.example.com:587
92
+ tls: STARTTLS
93
+ auth: authenticated as user@example.com
94
+ from: "My Agent" <agent@example.com>
95
+ restrictions: domains: example.com
96
+ ```
97
+
98
+ Returns `isError: true` if the connection test fails, with the SMTP error message included.
99
+
100
+ ---
101
+
102
+ ### `send_email`
79
103
 
80
104
  | Parameter | Type | Required | Description |
81
105
  |---|---|---|---|
@@ -95,9 +119,17 @@ For an unauthenticated internal relay, omit `SMTP_USER` and `SMTP_PASS`.
95
119
  | `content` | string | Base64-encoded file data |
96
120
  | `content_type` | string | MIME type, e.g. `application/pdf` |
97
121
 
122
+ ---
123
+
124
+ ## Resource: `smtp://server/usage`
125
+
126
+ A plain-text usage guide populated with the server's live configuration (sender identity, SMTP endpoint, active restrictions, full tool reference). Agents can read this resource to understand what options are available without calling any tools.
127
+
128
+ ---
129
+
98
130
  ## Local Testing with Mailpit
99
131
 
100
- [Mailpit](https://mailpit.axllent.org/) is a lightweight local SMTP catcher:
132
+ [Mailpit](https://mailpit.axllent.org/) is a lightweight local SMTP catcher — no credentials required:
101
133
 
102
134
  ```bash
103
135
  # macOS
@@ -107,4 +139,4 @@ brew install mailpit && mailpit
107
139
  scoop install mailpit && mailpit
108
140
  ```
109
141
 
110
- Then set `SMTP_HOST=localhost`, `SMTP_PORT=1025`, and leave `SMTP_USER`/`SMTP_PASS` as dummy values. View caught emails at http://localhost:8025.
142
+ Set `SMTP_HOST=localhost`, `SMTP_PORT=1025`, omit `SMTP_USER`/`SMTP_PASS`. View caught emails at http://localhost:8025.
package/dist/config.js CHANGED
@@ -15,6 +15,10 @@ const configSchema = zod_1.z.object({
15
15
  .string()
16
16
  .transform((v) => v.toLowerCase() === "true")
17
17
  .default(false),
18
+ ignoreTls: zod_1.z
19
+ .string()
20
+ .transform((v) => v.toLowerCase() === "true")
21
+ .default(false),
18
22
  user: zod_1.z.string().min(1).optional(),
19
23
  pass: zod_1.z.string().min(1).optional(),
20
24
  }),
@@ -41,6 +45,7 @@ function loadConfig() {
41
45
  host: process.env.SMTP_HOST,
42
46
  port: process.env.SMTP_PORT,
43
47
  secure: process.env.SMTP_SECURE,
48
+ ignoreTls: process.env.SMTP_IGNORE_TLS,
44
49
  user: process.env.SMTP_USER,
45
50
  pass: process.env.SMTP_PASS,
46
51
  },
package/dist/email.js CHANGED
@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.createTransport = createTransport;
7
+ exports.verifyTransport = verifyTransport;
7
8
  exports.sendEmail = sendEmail;
8
9
  const nodemailer_1 = __importDefault(require("nodemailer"));
9
10
  function createTransport(smtpConfig) {
@@ -11,11 +12,15 @@ function createTransport(smtpConfig) {
11
12
  host: smtpConfig.host,
12
13
  port: smtpConfig.port,
13
14
  secure: smtpConfig.secure,
15
+ ignoreTLS: smtpConfig.ignoreTls,
14
16
  ...(smtpConfig.user && smtpConfig.pass
15
17
  ? { auth: { user: smtpConfig.user, pass: smtpConfig.pass } }
16
18
  : {}),
17
19
  });
18
20
  }
21
+ async function verifyTransport(transport) {
22
+ await transport.verify();
23
+ }
19
24
  async function sendEmail(transport, from, options) {
20
25
  const message = {
21
26
  from: `"${from.name}" <${from.address}>`,
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ #!/usr/bin/env node
1
2
  "use strict";
2
3
  Object.defineProperty(exports, "__esModule", { value: true });
3
4
  const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
@@ -9,8 +10,11 @@ const email_js_1 = require("./email.js");
9
10
  const transport = (0, email_js_1.createTransport)(config_js_1.config.smtp);
10
11
  const server = new mcp_js_1.McpServer({
11
12
  name: "smtp-mcp",
12
- version: "1.0.0",
13
+ version: "1.1.2",
13
14
  });
15
+ // ---------------------------------------------------------------------------
16
+ // Shared schemas
17
+ // ---------------------------------------------------------------------------
14
18
  const attachmentSchema = zod_1.z.object({
15
19
  filename: zod_1.z.string().min(1),
16
20
  content: zod_1.z.string().min(1).describe("Base64-encoded file content"),
@@ -19,6 +23,54 @@ const attachmentSchema = zod_1.z.object({
19
23
  const recipientSchema = zod_1.z
20
24
  .union([zod_1.z.string().email(), zod_1.z.array(zod_1.z.string().email()).min(1)])
21
25
  .transform((v) => (Array.isArray(v) ? v : [v]));
26
+ // ---------------------------------------------------------------------------
27
+ // Tool: health
28
+ // ---------------------------------------------------------------------------
29
+ server.registerTool("health", {
30
+ description: "Check that the SMTP server is reachable and the configuration is valid. " +
31
+ "Returns the active settings (host, port, auth mode, sender identity, restrictions) " +
32
+ "and the result of a live connection test.",
33
+ }, async () => {
34
+ const start = Date.now();
35
+ let connectionStatus;
36
+ let isError = false;
37
+ try {
38
+ await (0, email_js_1.verifyTransport)(transport);
39
+ connectionStatus = `OK (${Date.now() - start} ms)`;
40
+ }
41
+ catch (err) {
42
+ connectionStatus = `FAILED — ${err instanceof Error ? err.message : String(err)}`;
43
+ isError = true;
44
+ }
45
+ const { allowedDomains, allowedAddresses } = config_js_1.config.restrictions;
46
+ const restrictionSummary = allowedDomains.length === 0 && allowedAddresses.length === 0
47
+ ? "none (all addresses permitted)"
48
+ : [
49
+ allowedDomains.length
50
+ ? `domains: ${allowedDomains.join(", ")}`
51
+ : null,
52
+ allowedAddresses.length
53
+ ? `addresses: ${allowedAddresses.join(", ")}`
54
+ : null,
55
+ ]
56
+ .filter(Boolean)
57
+ .join(" | ");
58
+ const lines = [
59
+ `connection: ${connectionStatus}`,
60
+ `smtp_host: ${config_js_1.config.smtp.host}:${config_js_1.config.smtp.port}`,
61
+ `tls: ${config_js_1.config.smtp.secure ? "implicit TLS" : config_js_1.config.smtp.ignoreTls ? "none (plain SMTP)" : "STARTTLS"}`,
62
+ `auth: ${config_js_1.config.smtp.user ? `authenticated as ${config_js_1.config.smtp.user}` : "unauthenticated"}`,
63
+ `from: "${config_js_1.config.from.name}" <${config_js_1.config.from.address}>`,
64
+ `restrictions: ${restrictionSummary}`,
65
+ ];
66
+ return {
67
+ isError,
68
+ content: [{ type: "text", text: lines.join("\n") }],
69
+ };
70
+ });
71
+ // ---------------------------------------------------------------------------
72
+ // Tool: send_email
73
+ // ---------------------------------------------------------------------------
22
74
  server.registerTool("send_email", {
23
75
  description: "Send an email via SMTP. Recipient addresses are validated against the server's allowed domains/addresses policy.",
24
76
  inputSchema: {
@@ -85,6 +137,98 @@ server.registerTool("send_email", {
85
137
  };
86
138
  }
87
139
  });
140
+ // ---------------------------------------------------------------------------
141
+ // Resource: usage guide for agents
142
+ // ---------------------------------------------------------------------------
143
+ function buildUsageText() {
144
+ const { allowedDomains, allowedAddresses } = config_js_1.config.restrictions;
145
+ const hasRestrictions = allowedDomains.length > 0 || allowedAddresses.length > 0;
146
+ const restrictionSection = hasRestrictions
147
+ ? [
148
+ "RECIPIENT RESTRICTIONS",
149
+ "An address is permitted when it satisfies at least one rule:",
150
+ allowedDomains.length
151
+ ? ` Allowed domains: ${allowedDomains.join(", ")}`
152
+ : null,
153
+ allowedAddresses.length
154
+ ? ` Allowed addresses: ${allowedAddresses.join(", ")}`
155
+ : null,
156
+ "Blocked addresses are rejected before any connection is made to the SMTP server.",
157
+ ]
158
+ .filter((l) => l !== null)
159
+ .join("\n")
160
+ : "RECIPIENT RESTRICTIONS\nNone configured — all addresses are permitted.";
161
+ return `
162
+ SMTP MCP SERVER — USAGE GUIDE
163
+ ==============================
164
+
165
+ This server sends email on behalf of agents via an SMTP relay.
166
+ All configuration (credentials, sender identity, restrictions) is fixed at
167
+ startup and cannot be changed by tool calls.
168
+
169
+ SENDER IDENTITY
170
+ From name: ${config_js_1.config.from.name}
171
+ From address: ${config_js_1.config.from.address}
172
+
173
+ SMTP ENDPOINT
174
+ Host: ${config_js_1.config.smtp.host}
175
+ Port: ${config_js_1.config.smtp.port}
176
+ TLS: ${config_js_1.config.smtp.secure ? "implicit TLS" : config_js_1.config.smtp.ignoreTls ? "none (plain SMTP)" : "STARTTLS"}
177
+ Auth: ${config_js_1.config.smtp.user ? "enabled" : "none"}
178
+
179
+ ${restrictionSection}
180
+
181
+ TOOLS
182
+ -----
183
+
184
+ health
185
+ No parameters.
186
+ Performs a live TCP+SMTP connection test and returns the active configuration.
187
+ Call this first to confirm the server is reachable before sending.
188
+
189
+ send_email
190
+ Required
191
+ to string | string[] One or more recipient email addresses.
192
+ subject string Subject line.
193
+ body string Message body (plain text or HTML).
194
+
195
+ Optional
196
+ body_type "text" | "html" Default: "text". Use "html" for rich content.
197
+ cc string | string[] Carbon copy recipients.
198
+ bcc string | string[] Blind carbon copy recipients.
199
+ attachments Attachment[] Files to attach (see schema below).
200
+
201
+ Attachment schema
202
+ filename string Name shown to the recipient (e.g. "report.pdf").
203
+ content string File data encoded as base64.
204
+ content_type string MIME type (e.g. "application/pdf", "image/png").
205
+
206
+ TIPS
207
+ ----
208
+ - Call health before send_email if you are unsure whether the relay is up.
209
+ - body_type defaults to plain text; only set "html" when you need formatting.
210
+ - All addresses in to, cc, and bcc are checked against restrictions — a single
211
+ blocked address will reject the entire request.
212
+ - Attachments have no size limit enforced by this server; the SMTP relay may
213
+ impose its own limits.
214
+ `.trim();
215
+ }
216
+ server.registerResource("usage", "smtp://server/usage", {
217
+ title: "SMTP MCP Server — Usage Guide",
218
+ description: "Reference guide describing this server's tools, parameters, active sender identity, and recipient restrictions.",
219
+ mimeType: "text/plain",
220
+ }, async () => ({
221
+ contents: [
222
+ {
223
+ uri: "smtp://server/usage",
224
+ text: buildUsageText(),
225
+ mimeType: "text/plain",
226
+ },
227
+ ],
228
+ }));
229
+ // ---------------------------------------------------------------------------
230
+ // Start
231
+ // ---------------------------------------------------------------------------
88
232
  async function main() {
89
233
  const stdio = new stdio_js_1.StdioServerTransport();
90
234
  await server.connect(stdio);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@teamnetwork-nz/smtp-mcp-server",
3
- "version": "1.0.0",
3
+ "version": "1.1.2",
4
4
  "description": "MCP server for sending email via SMTP relay",
5
5
  "main": "dist/index.js",
6
6
  "bin": {