titan-email-mcp 1.0.1 → 1.0.3

package/README.md

@@ -1,16 +1,26 @@
 # Titan Email MCP
 
+[![npm version](https://img.shields.io/npm/v/titan-email-mcp.svg)](https://www.npmjs.com/package/titan-email-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/titan-email-mcp.svg)](https://www.npmjs.com/package/titan-email-mcp)
+[![CI](https://github.com/qmmughal/titan-email-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/qmmughal/titan-email-mcp/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/titan-email-mcp.svg)](LICENSE)
+
 Connect Claude — Desktop, Code, Cursor, or any [MCP](https://modelcontextprotocol.io) client — directly to a **Titan Email** mailbox, so it can read, search, triage, and send mail on your behalf.
 
+Package: [npmjs.com/package/titan-email-mcp](https://www.npmjs.com/package/titan-email-mcp) · Source: [github.com/qmmughal/titan-email-mcp](https://github.com/qmmughal/titan-email-mcp)
+
 Titan Email (the mailbox product bundled with many domain registrars, including **GoDaddy**) has no public REST API. This server bridges that gap by talking to Titan's standard **IMAP** and **SMTP** endpoints instead, so your AI assistant gets real mailbox access without any vendor integration work.
 
+**Contents:** [Why use this](#why-use-this) · [Supported providers](#supported-providers) · [Tools](#tools) · [Quick start](#quick-start) · [Configuration](#configuration) · [Security notes](#security-notes) · [Troubleshooting](#troubleshooting) · [Development](#development) · [Contributing](#contributing) · [License](#license)
+
 ## Why use this
 
 - **Your inbox becomes an agent tool.** Ask Claude to summarize unread mail, draft replies in your voice, triage by sender, or find "that invoice from last March" — in plain English, in the same conversation you're already having.
 - **Works with GoDaddy-hosted Titan mailboxes.** If you bought your domain and mailbox through GoDaddy, your email is very likely running on Titan's infrastructure under the hood. One `TITAN_PROVIDER` setting handles the different server hostnames — see [Supported providers](#supported-providers).
 - **Safe by default.** Sending is gated behind `TITAN_ALLOW_SEND` (default **on**, but trivially switched **off**) so you can run Claude in read-only / draft-only mode until you trust it.
 - **No middleman service.** Credentials go straight from your MCP client's local config to Titan's own IMAP/SMTP servers over TLS. Nothing is proxied through a third party, cached, or logged to disk.
-- **One process, nine focused tools.** No bloated API surface — just the operations you actually do in a mailbox (see [Tools](#tools) below).
+- **One process, ten focused tools.** No bloated API surface — just the operations you actually do in a mailbox (see [Tools](#tools) below).
+- **Published on npm.** Run it with `npx titan-email-mcp` — no cloning or building required for everyday use.
 
 ## Supported providers
 
@@ -146,6 +156,8 @@ npm start        # run the built server directly (reads env vars from your shell
 
 The server speaks MCP over stdio (`StdioServerTransport`) — it's not an HTTP service, so running it directly just blocks waiting for a client on stdin.
 
+**Releasing a new version** (maintainers): bump `version` in `package.json`, run `npm run build` to confirm it compiles, commit and push, then `npm publish` from `titan-mcp/`. The package only ships `dist/`, `README.md`, and `LICENSE` (see `files` in `package.json`) — source TypeScript stays GitHub-only.
+
 ## Contributing
 
 Issues and PRs welcome at [github.com/qmmughal/titan-email-mcp](https://github.com/qmmughal/titan-email-mcp). If you add support for another Titan-based reseller, please add its hostnames to the provider preset table in `src/index.ts` and this README.

package/dist/index.js

@@ -24,8 +24,8 @@ if (!preset) {
 }
 const activePreset = preset ?? PROVIDER_PRESETS.titan;
 const cfg = {
-    user: req("TITAN_EMAIL"),
-    pass: req("TITAN_PASSWORD"),
+    user: process.env.TITAN_EMAIL ?? "",
+    pass: process.env.TITAN_PASSWORD ?? "",
     provider: preset ? providerName : "titan",
     imapHost: process.env.TITAN_IMAP_HOST ?? activePreset.imapHost,
     imapPort: Number(process.env.TITAN_IMAP_PORT ?? activePreset.imapPort),
@@ -36,16 +36,20 @@ const cfg = {
     sentFolder: process.env.TITAN_SENT_FOLDER ?? "Sent",
     draftsFolder: process.env.TITAN_DRAFTS_FOLDER ?? "Drafts",
 };
-function req(name) {
-    const v = process.env[name];
-    if (!v) {
-        console.error(`Missing required env var ${name}. Set TITAN_EMAIL and TITAN_PASSWORD in your MCP client's server config — see README.md for examples.`);
-        process.exit(1);
+// Tool schemas register unconditionally below, regardless of credentials, so clients
+// and directory crawlers can list this server's capabilities without live creds.
+// Credentials are only required once a tool actually tries to touch the mailbox.
+if (!cfg.user || !cfg.pass) {
+    console.error("TITAN_EMAIL / TITAN_PASSWORD not set — tools are registered but will return an error until both are configured in your MCP client's server config.");
+}
+function ensureCreds() {
+    if (!cfg.user || !cfg.pass) {
+        throw new Error("Missing TITAN_EMAIL and/or TITAN_PASSWORD. Set both in your MCP client's server config — see README.md for examples.");
     }
-    return v;
 }
 // ---------- helpers ----------
 async function withImap(fn) {
+    ensureCreds();
     const client = new ImapFlow({
         host: cfg.imapHost,
         port: cfg.imapPort,
@@ -280,6 +284,7 @@ server.registerTool("send_email", {
     if (!cfg.allowSend)
         return fail("Sending is disabled (TITAN_ALLOW_SEND=false). Use save_draft instead.");
     try {
+        ensureCreds();
         const mail = { from: fromAddr(), to: a.to, cc: a.cc, bcc: a.bcc, subject: a.subject, text: a.body, html: a.html };
         const info = await smtp.sendMail(mail);
         await appendCopy(cfg.sentFolder, await buildRaw({ ...mail, messageId: info.messageId }), ["\\Seen"]);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "titan-email-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP server that connects Claude (or any MCP client) to a Titan Email mailbox over IMAP/SMTP — including Titan accounts resold through GoDaddy.",
+  "mcpName": "io.github.qmmughal/titan-email-mcp",
   "main": "dist/index.js",
   "type": "module",
   "bin": {