Repository navigation
Releases: borystam/homepl-email-mcp
Release list
homepl-email-mcp v0.3.1
New installations and normal upgrades now resolve the current stable GitHub release at installation time, then verify and pin its exact tag and full source commit. README, AGENTS and one canonical installation runbook replace the old fixed-version handoffs. A copied prompt no longer selects an outdated release by default.
Upgrades preserve saved credentials, the OS user, data directory, read-only mode and existing MCP entry. mail_setup_status.connectorVersion identifies the code actually loaded by the MCP, so updating files on disk cannot be mistaken for reloading the desktop connection. Reuse working saved logins; do not remove accounts or request another password for an ordinary upgrade.
This patch also returns the actual MIME Message-ID for raw SMTP sends and reports explicit MAIL FROM rejection as a known sender rejection. Unknown/accepted sends are never retried automatically. Dependencies are unchanged.
Validation: 171 local synthetic tests and ten platform CI jobs. Real loopback regressions check exact wire/Sent MIME, Message-ID correlation and rejection/retry protection. Authorized live macOS checks previously verified drafts, attachments, SMTP delivery, Sent copies and saved-login reuse. Full client quit/reopen, OS logout/reboot and the affected Windows desktop remain unverified.
Source commit: b45aeb03cec9609213c46e588d1a466265c9de6a. Release metadata targets this full SHA. Verify checkout HEAD and package version before installing dependencies.
Source ZIP SHA-256: 551541de1e980b0db797a383435ce46e7fdfd54b291204090028e491d331d502. Verify the named ZIP against the accompanying SHA256SUMS asset.
Agent handoff: Install or update https://github.com/borystam/homepl-email-mcp to its latest stable GitHub release. Resolve the current release once, pin its tag and full source commit, and follow INSTALL_FOR_AGENTS.md from that release. Preserve saved logins, data paths and access mode. Register/reload the actual desktop MCP, compare its connectorVersion, and verify accounts/folders and a small metadata sample without sending or changing mail. Enter credentials only in its private form when a new login is actually required.
homepl-email-mcp v0.3.0
Superseded release. For a new installation or normal upgrade, use the latest stable release and current agent instructions. Do not choose this old tag from a copied prompt or cached download. Resolve the current release once, verify its full source commit, then follow that release’s runbook. Explicitly requested historical pins are the exception.
Agent prompt: Install or update https://github.com/borystam/homepl-email-mcp to its latest stable GitHub release. Resolve and pin its tag/full source commit. Follow INSTALL_FOR_AGENTS.md from that release, preserve saved logins and data/access mode, reload the actual desktop MCP and verify its loaded version and mailbox reads without sending or changing mail.
Historical release notes — not the current setup procedure
Mailbox onboarding now starts from the conversation through mail_setup and mail_setup_status. The existing private form and credential preflight run inside the actual MCP process. Passwords remain in that form and the OS credential store, never tool arguments/results or chat.
This changes the employee sequence: install source/dependencies → register and reload the active desktop MCP → inspect its actual execution identity → connect through mail_setup → verify native folder/message tools. Shell credential checks and CLI setup are no longer employee onboarding steps. Windows agent shells running as CodexSandboxOnline can lack a usable WinCred logon session; a shell failure does not determine the desktop MCP's access.
Known Windows sandbox identities are blocked before credential entry. A normal-looking username still must pass the native storage probe. If the desktop client also launches MCP in an unusable context, the agent must correct its supported local MCP entry or report that specific client block. This release does not change sandbox/logon policy, impersonate users, or provide plaintext password storage.
The tool returns a short-lived local URL, which the agent opens in the app browser when supported or provides as a private link. Only one wizard stays active; completion retires the URL, and MCP disconnect/stdio EOF closes it. Both mail access modes include local onboarding, with accurate local-write annotation. Full/read-only catalogs contain 20/10 tools; read-only mode still excludes mailbox writes.
Validation: 169 local synthetic tests and ten platform CI jobs. Tests exercise a real MCP/private-HTTP-form flow with synthetic credentials in both modes, secret/argument filtering, sandbox identity blocking, startup races, and child-process EOF cleanup. A clean production-only source archive installation passed 25 selected MCP/config/onboarding/trust checks. Existing native Windows/macOS storage and Windows OS-certificate tests remain enabled. No dependencies were added or changed.
The affected employee's Codex installation still needs a successful native identity/storage check, live folder read, and saved-login reuse after reopening the app. These automated tests do not establish universal plug-and-play behavior across Windows devices.
Source commit: 21e1557477225a84b426942fb5367360d586da0a. Compare the checkout's full HEAD before installing dependencies; do not rely solely on the mutable release tag.
Source ZIP SHA-256: 071dcc2519cd230e5dcef8996dd8359d45f3f1042260d262e935d40238f7f7ec.
homepl-email-mcp v0.2.1
Superseded release. For a new installation or normal upgrade, use the latest stable release and current agent instructions. Do not choose this old tag from a copied prompt or cached download. Resolve the current release once, verify its full source commit, then follow that release’s runbook. Explicitly requested historical pins are the exception.
Agent prompt: Install or update https://github.com/borystam/homepl-email-mcp to its latest stable GitHub release. Resolve and pin its tag/full source commit. Follow INSTALL_FOR_AGENTS.md from that release, preserve saved logins and data/access mode, reload the actual desktop MCP and verify its loaded version and mailbox reads without sending or changing mail.
Historical release notes — not the current setup procedure
Setup and later IMAP/SMTP use now include certificates already trusted by the operating system alongside Node's existing roots. This supports G DATA/company mail inspection while preserving certificate and hostname verification.
Setup checks the actual local data directory and a temporary OS-keyring credential before opening the private password form. Storage failures return fixed, safe stage codes. The installing agent's runbook owns prerequisites, dependency installation, ordinary local repair, saved-login reuse, MCP registration and actual tool verification; the employee enters mailbox details privately.
Native Node.js 22.19+ on 22.x or 24.6+ is required. Install the current patched LTS. Earlier Windows runtimes contain an upstream filesystem identity inconsistency; attachment/outbox checks remain intact.
Dependency review: all direct versions are exact; the full transitive tree is locked with integrity hashes, CI actions use commit SHAs, and install scripts are disabled by default and in install commands. npm reported zero known advisories; registry signatures verified for 146 installed packages and attestations for 29. These are registry checks, not a guarantee that source/native binaries contain no malicious code.
Validation: 153 local synthetic tests and ten platform CI jobs, including exact Windows runtime minima, native OS-root trust and hostname rejection, synthetic credential persistence across fresh processes, and actual-directory storage preflight. A clean source archive production installation passed stdio/config/trust checks. No real mailbox credentials or messages are included. The affected employee PC still needs the upgrade and live MCP verification.
Source commit: 0ae25fc6247e53337e97e77b97dc99d93bf996ab. Compare the checkout's full HEAD to this value before installing dependencies; do not rely solely on a mutable tag.
Source ZIP SHA-256: 6a1f2aa42c5905df4ea9c6706279032a86c21c55d2c765cbbd790d27cef559fe.
Install with a local computer-capable agent: ask it to install/update this release at the full commit above and follow INSTALL_FOR_AGENTS.md. It should perform diagnostics and integration itself, reuse any working saved login, and ask only for private mailbox details or genuine OS/policy consent. Passwords remain in the OS credential store; no plaintext fallback is provided.
homepl-email-mcp v0.2.0
Superseded release. For a new installation or normal upgrade, use the latest stable release and current agent instructions. Do not choose this old tag from a copied prompt or cached download. Resolve the current release once, verify its full source commit, then follow that release’s runbook. Explicitly requested historical pins are the exception.
Agent prompt: Install or update https://github.com/borystam/homepl-email-mcp to its latest stable GitHub release. Resolve and pin its tag/full source commit. Follow INSTALL_FOR_AGENTS.md from that release, preserve saved logins and data/access mode, reload the actual desktop MCP and verify its loaded version and mailbox reads without sending or changing mail.
Historical release notes — not the current setup procedure
Local home.pl email access for MCP-capable agents on Windows and macOS. Each user connects on their own computer; no hosted connector is required.
Install
Paste this into a local agent with terminal access and local stdio MCP support:
Install https://github.com/borystam/homepl-email-mcp at release v0.2.0. Follow INSTALL_FOR_AGENTS.md from that exact release, install prerequisites, configure the MCP in this client, and guide me through the private local mailbox login form. Never ask for my password in chat. Verify actual tools, folders, and up to three messages' metadata without sending or changing mail. Report any client reload still required.
Node.js 22+ is required. The attached source ZIP and SHA-256 checksum identify this release. Install pinned dependencies with npm ci --omit=dev --ignore-scripts.
Changes from v0.1.0
- Fix native browser form submissions rejected as Forbidden.
- Explain IMAP/SMTP authentication, network, TLS and folder-discovery failures using fixed safe messages.
- Add optional read-only tool discovery, bounded metadata-first batch reads, and reply/reply-all/forward server drafts.
- Fix reproduced MIME, recipient, pagination, SMTP outcome, attachment-path and concurrent account-update failures.
- Document Mac and Windows setup, Keychain/Credential Manager access, and saved-login verification across fresh processes.
Validation
133 automated tests passed locally. The release candidate is checked on Windows, macOS Apple silicon, macOS Intel and Ubuntu with Node.js 22/24. Windows/Mac CI also checks native saved credentials across fresh processes.
One authorized live Mac pilot verified IMAP/SMTP login, Keychain storage, discovery of 18 MCP tools, folder listing, metadata/header reads and saved-login reuse by a fresh process. After a user-confirmed Codex restart, native MCP account/folder calls, three metadata reads and one header read succeeded using the saved login. No messages were sent or changed during that pilot.
OS logout/reboot, Linux Secret Service persistence and shared-namespace coverage remain unverified. A single mailbox pilot does not establish all provider configurations. Retrieved mail may be processed by the selected AI service.
homepl-email-mcp v0.1.0
Superseded release. For a new installation or normal upgrade, use the latest stable release and current agent instructions. Do not choose this old tag from a copied prompt or cached download. Resolve the current release once, verify its full source commit, then follow that release’s runbook. Explicitly requested historical pins are the exception.
Agent prompt: Install or update https://github.com/borystam/homepl-email-mcp to its latest stable GitHub release. Resolve and pin its tag/full source commit. Follow INSTALL_FOR_AGENTS.md from that release, preserve saved logins and data/access mode, reload the actual desktop MCP and verify its loaded version and mailbox reads without sending or changing mail.
Historical release notes — not the current setup procedure
First public release of the local home.pl email MCP. Each employee installs it on their own computer; no central server is required.
Install
Ask a locally running MCP-capable agent:
Install https://github.com/borystam/homepl-email-mcp at release v0.1.0. Follow INSTALL_FOR_AGENTS.md, configure the local MCP server, and guide me through private mailbox login. I will enter my password in the local form, never in chat. Verify folders and up to three messages without sending or changing mail.
Node.js 22+ is required. The source ZIP and SHA-256 checksum are attached; dependencies install with npm ci --omit=dev --ignore-scripts.
Included
- Private local login form and OS credential storage.
- All retained server history through pagination; folders, metadata, repeated/raw headers, MIME trees and exact original EML downloads.
- Attachment download by MIME part, preserving binary contents.
- Prepare/send/reply/reply-all/forward, drafts, flags, move/copy/trash, exact permanent deletion and folder management.
- Durable send status to prevent blind retries; Bcc preserved in Sent copies and excluded from transmitted message headers.
Validation and limits
All 43 tests passed on Windows (Node.js 22/24), macOS (24), and Ubuntu (24), including local IMAP/SMTP and MCP protocol/stdio integration. Native credential-store round trips passed on Windows and macOS. A clean production-only installation and stdio launch passed on macOS. Linux Secret Service persistence was not exercised in CI.
Tests used synthetic local mail servers. A real home.pl mailbox has not yet been verified; the first employee must complete the guided live read check. Setup authenticates without sending mail. Only messages still stored on the server are accessible. Downloading any attachment format does not imply built-in OCR or interpretation of every format. Retrieved email may be sent to the chosen AI provider.
Installation runbook · Capabilities and limits · Platform CI