@miguelarios/email-mcp 0.16.0 → 0.17.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/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.17.0 (2026-10-07)
4
+
5
+ - Runs over Streamable HTTP as well as stdio: set `PIM_MCP_TRANSPORT=http` (see the README's "Over Streamable HTTP"). stdio stays the default and is unchanged on the wire.
6
+ - The IMAP and SMTP services are created once at startup and shared by every server instance, since over HTTP an instance is built per request or per session. Previously each instance built its own, each adding its own signal handlers — and over stdio a client that probes for 2026-07-28 before falling back to the 2025 handshake already got two. A configuration error now stops the process at startup instead of surfacing on the first connection.
7
+ - Bumped `@miguelarios/pim-core` dependency to `^0.15.0` for `serve`. The previous `^0.10.0` excluded every later core release, so the package was still built and tested against core 0.10.0 from npm.
8
+ - Documentation: a Docker guide (`docs/docker.md`) with an env file, `docker run` for stdio and HTTP, and Docker Compose; this README gains an "Over HTTP and in Docker" section and `URL_RESOLVE_TIMEOUT`; `docs/tools/email-mcp.md` was re-checked against the tool definitions — it now covers the `imap://` resources, the inline-size link fallback, every confirmation prompt, and the JSON error body.
9
+
3
10
  ## 0.16.0 (2026-09-23)
4
11
 
5
12
  - A plain reply now addresses itself. `send_email` with `replyToUid` and no `to` goes to the original's `Reply-To`, or its `From` when there is none — the same author `replyAll` starts from. Previously `to` was required, so the caller copied the sender's address by hand even though the tool had already fetched the original to thread it, and the easy mistake was copying `From` when `Reply-To` was set, which answers a mailing-list post privately instead of on the list (PR #120, `claude/repo-review-75x4of`).
package/README.md CHANGED
@@ -4,7 +4,7 @@ MCP server for email via IMAP/SMTP — search, read, send, and manage emails and
4
4
 
5
5
  ## Protocol support
6
6
 
7
- Speaks MCP revision **2026-07-28** over stdio, and still serves 2025-era clients from the same tool definitions.
7
+ Speaks MCP revision **2026-07-28** over stdio or Streamable HTTP, and still serves 2025-era clients from the same tool definitions.
8
8
  Every tool declares a `title`, all four behaviour annotations, and an `outputSchema`, and returns validated `structuredContent`.
9
9
 
10
10
  `send_email` and `forward_email` (when sending, not when saving a draft), `send_draft`, `delete_email` with `permanent: true`, and `delete_folder` ask the user to confirm first. Set `PIM_MCP_CONFIRM=off` to skip confirmation in headless use.
@@ -49,6 +49,7 @@ Optional env vars: `IMAP_PORT` (default 993), `IMAP_SECURE` (default true), `SMT
49
49
  top, and most clients put a tool result straight into the model's context, so raise it
50
50
  deliberately.
51
51
  - `EMAIL_ATTACHMENT_DIR` — directory that gates `send_email` file attachments. Path-based attachments (`attachments[].path`) are rejected unless this is set, and only files resolving inside it are allowed. Use `attachments[].content` for inline content without setting this.
52
+ - `URL_RESOLVE_TIMEOUT` — milliseconds allowed for each link-resolution fetch. Default `10000`.
52
53
  - `URL_RESOLVE_DISABLE` — set to `1`/`true` to skip network link-resolution when rendering email to markdown; links are left unresolved in the output.
53
54
  - `URL_RESOLVE_PROXY` — route link resolution through an HTTP proxy, so the machine running
54
55
  the server does not hand its IP address to every host an email links to. Takes an
@@ -78,6 +79,20 @@ server trust you.
78
79
  `SMTP_FROM_NAME` and the per-call `fromName` change only the display name, never the address, so they carry no
79
80
  deliverability risk. Prefer them when you just want a distinct agent identity on a shared mailbox.
80
81
 
82
+ ## Over HTTP and in Docker
83
+
84
+ Set `PIM_MCP_TRANSPORT=http` to serve Streamable HTTP at `/mcp` instead of stdio — for a client that connects by URL, or a server in a container. `PIM_MCP_HTTP_HOST` (default `127.0.0.1`) and `PIM_MCP_HTTP_PORT` (default `3000`) set where it listens, and `GET /healthz` answers `ok` for health checks. **The HTTP server does no authentication**: keep it on loopback or a private network, and put an OAuth proxy in front before exposing it further.
85
+
86
+ ```bash
87
+ docker run -d --name email-mcp --restart unless-stopped --user node \
88
+ --env-file email.env \
89
+ -e PIM_MCP_TRANSPORT=http -e PIM_MCP_HTTP_HOST=0.0.0.0 \
90
+ -p 127.0.0.1:3001:3000 -v email-mcp-home:/home/node \
91
+ node:22-alpine npx -y @miguelarios/email-mcp@0.17.0
92
+ ```
93
+
94
+ See the [Docker guide](https://github.com/miguelarios/pim-agents/blob/main/docs/docker.md) for the env file, stdio use from a desktop client, Docker Compose, and exposing a server safely, and the [README](https://github.com/miguelarios/pim-agents/blob/main/README.md#over-streamable-http) for every HTTP setting.
95
+
81
96
  ## Tools (17)
82
97
 
83
98
  See [docs/tools/email-mcp.md](../../docs/tools/email-mcp.md) for full parameter and output details.
package/dist/main.d.ts CHANGED
@@ -1,4 +1,10 @@
1
1
  import { McpServer } from "@modelcontextprotocol/server";
2
- export declare function createServer(): Promise<McpServer>;
2
+ import { type EmailServices } from "./tools/emailTools.js";
3
+ /**
4
+ * Builds one server instance around shared services. Called per connection on
5
+ * stdio and per request over HTTP, so it must not open connections or install
6
+ * process handlers of its own.
7
+ */
8
+ export declare function createServer(services: EmailServices): McpServer;
3
9
  export declare function startServer(): Promise<void>;
4
10
  //# sourceMappingURL=main.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAWzD,wBAAsB,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,CAiCvD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAOjD"}
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAKzD,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAKxE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAoB/D;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAkBjD"}
package/dist/main.js CHANGED
@@ -1,8 +1,7 @@
1
1
  import { createRequire } from "node:module";
2
2
  import { loadEmailConfig } from "@miguelarios/pim-core";
3
- import { TOOL_LIST_CACHE_HINT, registerTools } from "@miguelarios/pim-core/mcp";
3
+ import { TOOL_LIST_CACHE_HINT, registerTools, serve } from "@miguelarios/pim-core/mcp";
4
4
  import { McpServer } from "@modelcontextprotocol/server";
5
- import { serveStdio } from "@modelcontextprotocol/server/stdio";
6
5
  import { disposeUrlCleaner, disposeUrlProxy } from "./htmlToMarkdown.js";
7
6
  import { registerImapResources } from "./resources/imapResources.js";
8
7
  import { ImapService } from "./services/ImapService.js";
@@ -10,12 +9,12 @@ import { SmtpService } from "./services/SmtpService.js";
10
9
  import { EMAIL_TOOLS } from "./tools/emailTools.js";
11
10
  const require = createRequire(import.meta.url);
12
11
  const { version } = require("../package.json");
13
- export async function createServer() {
14
- const config = loadEmailConfig();
15
- const services = {
16
- imap: new ImapService(config),
17
- smtp: new SmtpService(config),
18
- };
12
+ /**
13
+ * Builds one server instance around shared services. Called per connection on
14
+ * stdio and per request over HTTP, so it must not open connections or install
15
+ * process handlers of its own.
16
+ */
17
+ export function createServer(services) {
19
18
  const server = new McpServer({ name: "@miguelarios/email-mcp", title: "IMAP/SMTP Email", version }, {
20
19
  capabilities: {
21
20
  tools: { listChanged: false },
@@ -28,20 +27,23 @@ export async function createServer() {
28
27
  });
29
28
  registerTools(server, EMAIL_TOOLS, services);
30
29
  registerImapResources(server, services.imap);
30
+ return server;
31
+ }
32
+ export async function startServer() {
33
+ const config = loadEmailConfig();
34
+ const services = {
35
+ imap: new ImapService(config),
36
+ smtp: new SmtpService(config),
37
+ };
38
+ // PIM_MCP_TRANSPORT picks stdio or Streamable HTTP; either way the entry
39
+ // serves 2026-07-28 and 2025-era clients from the same factory.
40
+ const handle = await serve(() => createServer(services), { name: "email-mcp" });
31
41
  const handleShutdown = async () => {
42
+ await handle.close();
32
43
  await Promise.all([disposeUrlCleaner(), disposeUrlProxy()]);
33
44
  process.exit(0);
34
45
  };
35
46
  process.on("SIGINT", handleShutdown);
36
47
  process.on("SIGTERM", handleShutdown);
37
- return server;
38
- }
39
- export async function startServer() {
40
- // `serveStdio` owns the era decision: a 2026-07-28 client gets the new
41
- // protocol, and a 2025-era client is still served from the same factory.
42
- serveStdio(() => createServer(), {
43
- onerror: (error) => console.error("[email-mcp] Server error:", error.message),
44
- });
45
- console.error("[email-mcp] Server started on stdio");
46
48
  }
47
49
  //# sourceMappingURL=main.js.map
package/dist/main.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,IAAI,WAAW,CAAC,MAAM,CAAC;QAC7B,IAAI,EAAE,IAAI,WAAW,CAAC,MAAM,CAAC;KAC9B,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,EACrE;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;YAC7B,qEAAqE;YACrE,8BAA8B;YAC9B,SAAS,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;SAClC;QACD,YAAY,EACV,+WAA+W;QACjX,UAAU,EAAE,EAAE,YAAY,EAAE,oBAAoB,EAAE;KACnD,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC7C,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE7C,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE;QAChC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAEtC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,uEAAuE;IACvE,yEAAyE;IACzE,UAAU,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,EAAE;QAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,KAAK,CAAC,OAAO,CAAC;KAC9E,CAAC,CAAC;IACH,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;AACvD,CAAC"}
1
+ {"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAsB,MAAM,uBAAuB,CAAC;AAExE,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAuB;IAClD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,EACrE;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;YAC7B,qEAAqE;YACrE,8BAA8B;YAC9B,SAAS,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;SAClC;QACD,YAAY,EACV,+WAA+W;QACjX,UAAU,EAAE,EAAE,YAAY,EAAE,oBAAoB,EAAE;KACnD,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC7C,qBAAqB,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,IAAI,WAAW,CAAC,MAAM,CAAC;QAC7B,IAAI,EAAE,IAAI,WAAW,CAAC,MAAM,CAAC;KAC9B,CAAC;IAEF,yEAAyE;IACzE,gEAAgE;IAChE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IAEhF,MAAM,cAAc,GAAG,KAAK,IAAI,EAAE;QAChC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,iBAAiB,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AACxC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miguelarios/email-mcp",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "MCP server for email via IMAP/SMTP — read, search, send, and manage emails",
5
5
  "keywords": [
6
6
  "mcp",
@@ -34,7 +34,7 @@
34
34
  },
35
35
  "dependencies": {
36
36
  "@backrunner/url-cleaner": "^0.1.0",
37
- "@miguelarios/pim-core": "^0.10.0",
37
+ "@miguelarios/pim-core": "^0.15.0",
38
38
  "@modelcontextprotocol/server": "^2.0.0",
39
39
  "imapflow": "^1.0.0",
40
40
  "mailparser": "^3.7.0",