@mailkite/mcp 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.4.0",
+  "version": "0.5.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": {
@@ -41,6 +41,6 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.4.0"
+    "mailkite": "^0.5.0"
   }
 }

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.4.0",
+  "version": "0.5.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": {
@@ -25,6 +25,22 @@
       ],
       "returns": "send-response"
     },
+    {
+      "name": "uploadAttachment",
+      "summary": "Upload a file to MailKite storage and get back a secure, time-limited URL. Reference the returned `url` as an attachment in send() (`{ filename, url }`) or link it inline in your HTML — instead of base64-inlining large files on every send. `content` is the file bytes, base64-encoded; `retentionDays` (7/30/90/365, default 7) sets how long the file and URL live.",
+      "http": {
+        "method": "POST",
+        "path": "/v1/attachments"
+      },
+      "args": [
+        {
+          "name": "file",
+          "in": "body",
+          "schema": "upload-attachment-request"
+        }
+      ],
+      "returns": "upload-attachment-response"
+    },
     {
       "name": "listTemplates",
       "summary": "List your saved email templates (light metadata only — no body). Use getTemplate for the full template.",
@@ -348,6 +364,30 @@
       "returns": "string",
       "sdkOnly": true
     },
+    {
+      "name": "replySpam",
+      "summary": "Control-mode reply a webhook consumer returns to tell MailKite to mark the message as spam — the string `{\"status\":\"spam\"}`. Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "replyDrop",
+      "summary": "Control-mode reply a webhook consumer returns to tell MailKite to drop (discard) the message — the string `{\"status\":\"drop\"}`. Local, no network call.",
+      "local": true,
+      "args": [],
+      "returns": "string",
+      "sdkOnly": true
+    },
+    {
+      "name": "replyBlockSender",
+      "summary": "Control-mode reply a webhook consumer returns to tell MailKite to block the sender — the string `{\"status\":\"ok\",\"actions\":[{\"type\":\"block-sender\"}]}`. 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.",

package/spec/cases.json

@@ -34,6 +34,44 @@
         "status": "queued"
       }
     },
+    {
+      "name": "upload_attachment",
+      "method": "uploadAttachment",
+      "args": {
+        "filename": "po.pdf",
+        "content": "JVBERi0xLjQK",
+        "contentType": "application/pdf"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/v1/attachments",
+        "bodySchema": "upload-attachment-request",
+        "body": {
+          "filename": "po.pdf",
+          "content": "JVBERi0xLjQK",
+          "contentType": "application/pdf"
+        }
+      },
+      "response": {
+        "status": 201,
+        "body": {
+          "id": "7d/usr_demo/0a1b2c3d/po.pdf",
+          "url": "https://api.mailkite.dev/up/7d/usr_demo/0a1b2c3d/po.pdf?exp=1799999999&sig=deadbeef",
+          "filename": "po.pdf",
+          "contentType": "application/pdf",
+          "size": 9,
+          "expiresAt": "2026-07-02T00:00:00.000Z"
+        }
+      },
+      "result": {
+        "id": "7d/usr_demo/0a1b2c3d/po.pdf",
+        "url": "https://api.mailkite.dev/up/7d/usr_demo/0a1b2c3d/po.pdf?exp=1799999999&sig=deadbeef",
+        "filename": "po.pdf",
+        "contentType": "application/pdf",
+        "size": 9,
+        "expiresAt": "2026-07-02T00:00:00.000Z"
+      }
+    },
     {
       "name": "send_full",
       "method": "send",
@@ -876,6 +914,27 @@
       "args": {},
       "result": "{\"status\":\"ok\"}"
     },
+    {
+      "name": "reply_spam",
+      "method": "replySpam",
+      "local": true,
+      "args": {},
+      "result": "{\"status\":\"spam\"}"
+    },
+    {
+      "name": "reply_drop",
+      "method": "replyDrop",
+      "local": true,
+      "args": {},
+      "result": "{\"status\":\"drop\"}"
+    },
+    {
+      "name": "reply_block_sender",
+      "method": "replyBlockSender",
+      "local": true,
+      "args": {},
+      "result": "{\"status\":\"ok\",\"actions\":[{\"type\":\"block-sender\"}]}"
+    },
     {
       "name": "decrypt_envelope",
       "method": "decrypt",

package/spec/schemas/send-request.json

@@ -37,9 +37,9 @@
         "required": ["filename"],
         "properties": {
           "filename": { "type": "string" },
-          "url": { "type": "string" },
-          "content": { "type": "string" },
-          "contentType": { "type": "string" }
+          "url": { "type": "string", "description": "Fetch the file from this URL at send time and attach it. Any URL works; an uploadAttachment() URL is the secure, recommended choice. Prefer this over `content` for large files." },
+          "content": { "type": "string", "description": "Inline file bytes as base64. Simple for tiny files, but re-uploaded on every send — use `url` (see uploadAttachment) for anything large." },
+          "contentType": { "type": "string", "description": "MIME type; defaults to application/octet-stream." }
         }
       }
     }

package/spec/schemas/upload-attachment-request.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "upload-attachment-request",
+  "title": "Upload attachment request body",
+  "type": "object",
+  "required": ["filename", "content"],
+  "additionalProperties": false,
+  "properties": {
+    "filename": { "type": "string", "description": "The file's name, e.g. \"invoice.pdf\". Shown to recipients on download." },
+    "content": { "type": "string", "description": "The file bytes, base64-encoded." },
+    "contentType": { "type": "string", "description": "MIME type, e.g. \"application/pdf\". Defaults to application/octet-stream." },
+    "retentionDays": {
+      "type": "integer",
+      "enum": [7, 30, 90, 365],
+      "description": "How long the file (and its signed URL) stays valid. One of 7, 30, 90, 365. Defaults to 7."
+    }
+  }
+}

package/spec/schemas/upload-attachment-response.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "upload-attachment-response",
+  "title": "Upload attachment response",
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Storage key for the uploaded file." },
+    "url": { "type": "string", "description": "Secure, time-limited URL. Pass it as an attachment's `url` in send(), or link it inline in your HTML." },
+    "filename": { "type": "string" },
+    "contentType": { "type": "string" },
+    "size": { "type": "integer", "description": "Stored size in bytes." },
+    "expiresAt": { "type": "string", "description": "ISO-8601 timestamp when the file and URL expire." }
+  }
+}