@mailkite/mcp 0.2.0 → 0.4.0

package/README.md

@@ -10,6 +10,19 @@ from the shared SDK contract in [`../spec`](../spec); transport, auth, and error
 handling come from the [MailKite Node SDK](../node). Nothing about the API is
 duplicated here — update the spec and the MCP follows.
 
+> ### Hosted vs local — which should I use?
+>
+> Most users should connect to the **hosted remote MCP** instead of running this
+> package: `https://mcp.mailkite.dev/mcp` (Streamable HTTP, one-click **OAuth** — no
+> key to copy, no local process). In Claude Code that's the **plugin**
+> (`/plugin marketplace add mailkite/claude-code` → `/plugin install mailkite@mailkite`)
+> or `claude mcp add --transport http mailkite https://mcp.mailkite.dev/mcp`. See
+> <https://mailkite.dev/docs/ai-agents>.
+>
+> Run **this local server** when you want a **static key** (no browser OAuth), **offline /
+> CI** use, a stdio-only client, a custom `MAILKITE_BASE_URL`, or `verifyWebhook` to run
+> fully locally. Both expose the exact same tools (same `../spec`).
+
 ## Install / configure
 
 Point your MCP client at the server and give it your MailKite credential. The
@@ -40,6 +53,8 @@ One tool per MailKite API operation (generated from [`../spec/api.json`](../spec
 | Tool | Operation |
 | --- | --- |
 | `mailkite_send` | Send a message over a verified domain |
+| `mailkite_agent` | Send a message to an inbox agent and get its reply |
+| `mailkite_route` | Route a message to a registered route and run its action |
 | `mailkite_list_domains` | List your domains |
 | `mailkite_create_domain` | Add a domain (returns DNS records) |
 | `mailkite_get_domain` | Get one domain with DNS + webhook |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Model Context Protocol server for MailKite — exposes the MailKite API to LLM agents as tools. A thin layer over the MailKite Node SDK and the shared sdks/spec contract.",
   "type": "module",
   "bin": {
@@ -34,13 +34,13 @@
   "homepage": "https://mailkite.dev/docs/libraries",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fijiwebdesign/mailkite.git",
+    "url": "git+https://github.com/mailkite/mailkite.git",
     "directory": "sdks/mcp"
   },
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.2.0"
+    "mailkite": "^0.4.0"
   }
 }

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Canonical interface contract for every MailKite SDK. One low-level request() plus one function per endpoint. All languages expose the same shape; only naming adapts to each language's convention (e.g. Go exports PascalCase).",
   "baseUrl": "https://api.mailkite.dev",
   "auth": {
@@ -11,126 +11,370 @@
   "methods": [
     {
       "name": "send",
-      "summary": "Send a message over a verified domain.",
-      "http": { "method": "POST", "path": "/v1/send" },
-      "args": [{ "name": "message", "in": "body", "schema": "send-request" }],
+      "summary": "Send a message over a verified domain. Pass `templateId` (+ optional `templateData`) to send from a saved or base template.",
+      "http": {
+        "method": "POST",
+        "path": "/v1/send"
+      },
+      "args": [
+        {
+          "name": "message",
+          "in": "body",
+          "schema": "send-request"
+        }
+      ],
       "returns": "send-response"
     },
+    {
+      "name": "listTemplates",
+      "summary": "List your saved email templates (light metadata only — no body). Use getTemplate for the full template.",
+      "http": {
+        "method": "GET",
+        "path": "/api/templates"
+      },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "listBaseTemplates",
+      "summary": "List the premade base templates (light metadata). Clone one with createTemplate({ baseId }) or send from it directly via send({ templateId }).",
+      "http": {
+        "method": "GET",
+        "path": "/api/templates/base"
+      },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "getTemplate",
+      "summary": "Get one template (full: subject, html, text, theme). Works for your templates (tpl_…) and base templates (base_…).",
+      "http": {
+        "method": "GET",
+        "path": "/api/templates/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "createTemplate",
+      "summary": "Create a template. Pass `baseId` to clone a base template into your own, or provide name/subject/html/text/theme directly.",
+      "http": {
+        "method": "POST",
+        "path": "/api/templates"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-template-request"
+        }
+      ],
+      "returns": "any"
+    },
     {
       "name": "listDomains",
       "summary": "List your domains, each with its webhook URL.",
-      "http": { "method": "GET", "path": "/api/domains" },
+      "http": {
+        "method": "GET",
+        "path": "/api/domains"
+      },
       "args": [],
       "returns": "any"
     },
     {
       "name": "createDomain",
       "summary": "Add a domain. Returns the domain + DNS records.",
-      "http": { "method": "POST", "path": "/api/domains" },
-      "args": [{ "name": "body", "in": "body", "schema": "create-domain-request" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/domains"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-domain-request"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "getDomain",
       "summary": "Get one domain with DNS records + webhook.",
-      "http": { "method": "GET", "path": "/api/domains/{id}" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "GET",
+        "path": "/api/domains/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "deleteDomain",
       "summary": "Remove a domain.",
-      "http": { "method": "DELETE", "path": "/api/domains/{id}" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "DELETE",
+        "path": "/api/domains/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "verifyDomain",
       "summary": "Check DNS and update status.",
-      "http": { "method": "POST", "path": "/api/domains/{id}/verify" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/domains/{id}/verify"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "setWebhook",
       "summary": "Set or replace the domain's catch-all webhook.",
-      "http": { "method": "PUT", "path": "/api/domains/{id}/webhook" },
+      "http": {
+        "method": "PUT",
+        "path": "/api/domains/{id}/webhook"
+      },
       "args": [
-        { "name": "id", "in": "path" },
-        { "name": "body", "in": "body", "schema": "set-webhook-request" }
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "set-webhook-request"
+        }
       ],
       "returns": "any"
     },
     {
       "name": "deleteWebhook",
       "summary": "Remove the domain's webhook.",
-      "http": { "method": "DELETE", "path": "/api/domains/{id}/webhook" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "DELETE",
+        "path": "/api/domains/{id}/webhook"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "testWebhook",
       "summary": "Send a signed test event to the domain's webhook.",
-      "http": { "method": "POST", "path": "/api/domains/{id}/webhook/test" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/domains/{id}/webhook/test"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "checkDomainAvailability",
       "summary": "Check whether a domain is available to register, and at what price. Read-only — no charge.",
-      "http": { "method": "GET", "path": "/api/domains/register/check" },
-      "args": [{ "name": "domain", "in": "query" }],
+      "http": {
+        "method": "GET",
+        "path": "/api/domains/register/check"
+      },
+      "args": [
+        {
+          "name": "domain",
+          "in": "query"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "registerDomain",
       "summary": "Register (buy) a domain on the customer's behalf; provisions mail DNS and adds it to the account in one call. Charges the registrar.",
-      "http": { "method": "POST", "path": "/api/domains/register" },
-      "args": [{ "name": "body", "in": "body", "schema": "register-domain-request" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/domains/register"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "register-domain-request"
+        }
+      ],
       "returns": "any",
       "agentConfirm": true
     },
     {
       "name": "listRoutes",
       "summary": "List inbound routing rules.",
-      "http": { "method": "GET", "path": "/api/routes" },
+      "http": {
+        "method": "GET",
+        "path": "/api/routes"
+      },
       "args": [],
       "returns": "any"
     },
     {
       "name": "createRoute",
       "summary": "Create a route (match, action, destination).",
-      "http": { "method": "POST", "path": "/api/routes" },
-      "args": [{ "name": "body", "in": "body", "schema": "create-route-request" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/routes"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-route-request"
+        }
+      ],
       "returns": "any"
     },
+    {
+      "name": "agent",
+      "summary": "Send a message to one of your inbox agents and get its reply. Defaults to the account's default agent; pass `routeId` or `address` to target a specific agent, or `model` to override the model. This is separate from inbound routing — it does not match or override routes.",
+      "http": {
+        "method": "POST",
+        "path": "/v1/agent"
+      },
+      "args": [
+        {
+          "name": "message",
+          "in": "body",
+          "schema": "agent-request"
+        }
+      ],
+      "returns": "agent-response"
+    },
+    {
+      "name": "route",
+      "summary": "Route a message to one of your registered routes (by `routeId` or `address`), running that route's action — agent, webhook, or forward. The route must already exist on your account; arbitrary destinations are not allowed.",
+      "http": {
+        "method": "POST",
+        "path": "/v1/route"
+      },
+      "args": [
+        {
+          "name": "message",
+          "in": "body",
+          "schema": "route-message-request"
+        }
+      ],
+      "returns": "route-response"
+    },
     {
       "name": "listMessages",
       "summary": "List stored messages.",
-      "http": { "method": "GET", "path": "/api/messages" },
+      "http": {
+        "method": "GET",
+        "path": "/api/messages"
+      },
       "args": [],
       "returns": "any"
     },
     {
       "name": "getMessage",
       "summary": "Get a message with deliveries + attachments.",
-      "http": { "method": "GET", "path": "/api/messages/{id}" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "GET",
+        "path": "/api/messages/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "retryDelivery",
       "summary": "Re-deliver a stored message to its webhook.",
-      "http": { "method": "POST", "path": "/api/deliveries/{id}/retry" },
-      "args": [{ "name": "id", "in": "path" }],
+      "http": {
+        "method": "POST",
+        "path": "/api/deliveries/{id}/retry"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
       "returns": "any"
     },
     {
       "name": "verifyWebhook",
       "summary": "Verify the `x-mailkite-signature` header on an inbound webhook delivery. Runs entirely locally (HMAC-SHA256 over `${t}.${payload}`) — no network call. Returns true only when the signature matches and the event is within the freshness window.",
       "local": true,
-      "args": [{ "name": "body", "in": "body", "schema": "verify-webhook-request" }],
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "verify-webhook-request"
+        }
+      ],
       "returns": "boolean"
+    },
+    {
+      "name": "replyOk",
+      "summary": "The acknowledgement body a webhook consumer returns to confirm it processed the event — the string `{\"status\":\"ok\"}`. Send it with a 2xx when the route is in `ack` mode (or always — it's harmless in `lenient` mode). Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "encrypt",
+      "summary": "Encrypt a UTF-8 string to a domain's RSA public key (SPKI/PEM), returning the at-rest envelope JSON (`{v,keyAlg,fp,enc,iv,wrappedKey,ciphertext}`). Hybrid scheme: a fresh AES-256-GCM content key wrapped with RSA-OAEP(SHA-256) — byte-compatible with MailKite's own at-rest encryption. Local, no network call.",
+      "local": true,
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "encrypt-request"
+        }
+      ],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "decrypt",
+      "summary": "Decrypt a MailKite at-rest envelope JSON with your RSA private key (PKCS8/PEM), returning the original UTF-8 string. Reverses `encrypt` / MailKite's at-rest encryption (RSA-OAEP(SHA-256) unwrap → AES-256-GCM open). Local, no network call.",
+      "local": true,
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "decrypt-request"
+        }
+      ],
+      "returns": "string",
+      "sdkOnly": true
     }
   ]
 }