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