titan-email-mcp 1.0.2 → 1.0.4

package/README.md

@@ -7,20 +7,21 @@
 
 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)
+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) · Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.qmmughal/titan-email-mcp) as `io.github.qmmughal/titan-email-mcp`, and on [Smithery](https://smithery.ai/servers/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)
+**Contents:** [Why use this](#why-use-this) · [Supported providers](#supported-providers) · [Tools](#tools) · [Quick start](#quick-start) · [GoDaddy users — ready-to-paste config](#godaddy-users--ready-to-paste-config) · [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).
+- **✅ Tested and confirmed working 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, 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.
+- **Discoverable.** Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.qmmughal/titan-email-mcp) and on [Smithery](https://smithery.ai/servers/qmmughal/titan-email-mcp), so MCP clients and directories that browse those registries can find and install it directly.
 
 ## Supported providers
 
@@ -31,6 +32,8 @@ Titan Email is used directly (`imap.titan.email` / `smtp.titan.email`) and resol
 | `titan` (default) | `imap.titan.email` | `smtp.titan.email` | You signed up for Titan Email directly, or your registrar just says "Titan Email". |
 | `godaddy` | `imap.secureserver.net` | `smtpout.secureserver.net` | Your domain **and mailbox** were purchased through GoDaddy. |
 
+`godaddy` has been tested against a live GoDaddy-hosted Titan mailbox and confirmed working.
+
 If your reseller uses yet another hostname, leave `TITAN_PROVIDER` unset and override `TITAN_IMAP_HOST` / `TITAN_IMAP_PORT` / `TITAN_SMTP_HOST` / `TITAN_SMTP_PORT` directly — check your provider's welcome email or webmail settings page for the exact values. Explicit host/port variables always win over the preset.
 
 ## Tools
@@ -106,6 +109,44 @@ claude mcp add titan-email --scope user \
 
 Use `--scope project` instead of `--scope user` to make it available only inside one repo (written to `.mcp.json`, safe to share with a team since it carries no secrets by itself — just don't commit real credentials into it).
 
+### GoDaddy users — ready-to-paste config
+
+If your domain **and mailbox** were purchased through GoDaddy, your email almost certainly runs on Titan's infrastructure under GoDaddy's own hostnames, not Titan's. This has been tested end-to-end against a live GoDaddy-hosted Titan mailbox — you don't need to look those hostnames up yourself; just use `TITAN_PROVIDER=godaddy` and everything else works exactly the same as above:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "titan-email": {
+      "command": "npx",
+      "args": ["-y", "titan-email-mcp"],
+      "env": {
+        "TITAN_EMAIL": "you@yourdomain.com",
+        "TITAN_PASSWORD": "your-godaddy-mailbox-password",
+        "TITAN_PROVIDER": "godaddy",
+        "TITAN_FROM_NAME": "Your Name",
+        "TITAN_ALLOW_SEND": "false"
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add titan-email --scope user \
+  -e TITAN_EMAIL=you@yourdomain.com \
+  -e TITAN_PASSWORD=your-godaddy-mailbox-password \
+  -e TITAN_PROVIDER=godaddy \
+  -e TITAN_FROM_NAME="Your Name" \
+  -e TITAN_ALLOW_SEND=false \
+  -- npx -y titan-email-mcp
+```
+
+Before either one works, enable IMAP/SMTP access in GoDaddy's **Email & Office** settings (same "allow other apps" toggle mentioned in step 1 above — GoDaddy's webmail may label it slightly differently than Titan's own). Then run `test_connection` to confirm. If `godaddy` doesn't work for your specific plan, your mailbox may be on a different GoDaddy backend — check **Email & Office → Settings → Email Setup** in your GoDaddy dashboard for the exact IMAP/SMTP hostnames and override `TITAN_IMAP_HOST`/`TITAN_SMTP_HOST` directly (see [Configuration](#configuration)).
+
 ### Cursor and other MCP clients
 
 Any client that supports the standard `mcpServers` JSON shape (`command` / `args` / `env`) works the same way — use the Claude Desktop block above as a template and drop it into that client's MCP config file.
@@ -142,8 +183,9 @@ Run `list_folders` once after setup to confirm the exact Sent/Drafts folder name
 |---|---|
 | `test_connection` → `imap.status: "failed: ... Authentication failed"` | IMAP/SMTP access isn't enabled on the account yet, or the password is wrong. Re-check Settings → Enable Titan on other apps. |
 | Works for GoDaddy mailbox, fails with default settings | Set `TITAN_PROVIDER=godaddy`. |
+| GoDaddy mailbox still fails with `TITAN_PROVIDER=godaddy` | Your plan may use a different GoDaddy backend than `imap.secureserver.net`. Check **Email & Office → Settings → Email Setup** in your GoDaddy dashboard for the exact hostnames and set `TITAN_IMAP_HOST`/`TITAN_SMTP_HOST` directly — see [Configuration](#configuration). |
 | Connection times out | A firewall or VPN is blocking outbound 993/465. Try from a different network to confirm. |
-| MCP client shows the server as failed immediately on startup | `TITAN_EMAIL` or `TITAN_PASSWORD` is missing from the `env` block — this server exits immediately (by design) if either is unset; check the client's MCP server logs for the exact message. |
+| Every tool call returns "Missing TITAN_EMAIL and/or TITAN_PASSWORD" | Both are missing from the client's `env` block. Tools still appear in the client (by design, so directories can list them), but every call will fail until both are set. |
 | `send_email` returns an error about sending being disabled | `TITAN_ALLOW_SEND` is `false`. Use `save_draft` or `reply_email` with `draft_only: true`, or flip the flag on. |
 
 ## Development
@@ -156,7 +198,7 @@ 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.
+**Releasing a new version** (maintainers): bump `version` in `package.json` (and the matching `version` fields in `server.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. After the npm publish lands, update the [MCP Registry](https://registry.modelcontextprotocol.io) listing with `mcp-publisher publish` (requires `mcp-publisher login github` once per session — see the [registry quickstart](https://modelcontextprotocol.io/registry/quickstart)), then tag a GitHub release (`gh release create vX.Y.Z`) so Smithery's crawler picks up the new version via `smithery.yaml`.
 
 ## Contributing
 

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,7 @@
 {
   "name": "titan-email-mcp",
-  "version": "1.0.2",
-  "description": "MCP server that connects Claude (or any MCP client) to a Titan Email mailbox over IMAP/SMTP — including Titan accounts resold through GoDaddy.",
+  "version": "1.0.4",
+  "description": "MCP server that connects Claude (or any MCP client) to a Titan Email mailbox over IMAP/SMTP — tested and confirmed working with Titan accounts resold through GoDaddy.",
   "mcpName": "io.github.qmmughal/titan-email-mcp",
   "main": "dist/index.js",
   "type": "module",