@mailkite/mcp 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.4.0",
+  "version": "0.6.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.6.0"
   }
 }

package/server.mjs

@@ -202,6 +202,25 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     };
   }
 
+  // uploadAttachment is the one method whose input isn't a plain JSON body: `path` is read
+  // off the local disk and streamed as a raw binary upload. The generic resolveCall →
+  // mk.request() path only does JSON, so delegate to the SDK method, which picks the
+  // transport (path/bytes → binary, url/content → JSON). Validate against the same schema.
+  if (tool._method.name === "uploadAttachment") {
+    try {
+      const input = req.params.arguments || {};
+      const validate = validators["upload-attachment-request"];
+      if (validate && !validate(input)) {
+        return { isError: true, content: [{ type: "text", text: `Invalid input for upload-attachment-request: ${ajv.errorsText(validate.errors)}` }] };
+      }
+      const result = await mk.uploadAttachment(input);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      const text = err instanceof MailKiteError ? `MailKite API error ${err.status}: ${err.message}` : `Error: ${err.message}`;
+      return { isError: true, content: [{ type: "text", text }] };
+    }
+  }
+
   try {
     const { method, urlPath, body } = resolveCall(tool._method, req.params.arguments);
     const result = await mk.request(method, urlPath, body);

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.4.0",
+  "version": "0.6.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. Give the file ONE of four ways: a local `path` (read and streamed as raw bytes by the CLI/SDK/local MCP), a remote `url` (MailKite fetches and re-hosts it), base64 `content`, or — over raw HTTP — the file bytes as the POST body with `?filename=`. `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,82 @@
         "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": "upload_attachment_url",
+      "method": "uploadAttachment",
+      "args": {
+        "url": "https://files.example.com/po.pdf",
+        "filename": "po.pdf",
+        "contentType": "application/pdf"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/v1/attachments",
+        "bodySchema": "upload-attachment-request",
+        "body": {
+          "url": "https://files.example.com/po.pdf",
+          "filename": "po.pdf",
+          "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 +952,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,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "upload-attachment-request",
+  "title": "Upload attachment request body",
+  "description": "Provide the file ONE of four ways: `path` (a local file the SDK/CLI/MCP reads and streams as raw bytes), `url` (a remote file MailKite fetches and re-hosts), `content` (base64-encoded bytes), or — at the HTTP layer — the raw file bytes as the POST body with `?filename=`. `path`/raw-bytes go up as a real binary upload (like an S3/R2 PUT); `url`/`content` go up as JSON.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "filename": { "type": "string", "description": "The file's name, e.g. \"invoice.pdf\". Shown to recipients on download. Optional when it can be derived from `path` or `url`." },
+    "path": { "type": "string", "description": "Local filesystem path to the file. Read client-side by the CLI, SDKs, and the local MCP server, then uploaded as raw bytes. Not available on the hosted MCP (no filesystem)." },
+    "url": { "type": "string", "description": "A remote http(s) URL. MailKite fetches it and re-hosts the bytes under your account. Max 25 MB." },
+    "content": { "type": "string", "description": "The file bytes, base64-encoded. The lowest-common-denominator fallback when you can't send a path, URL, or raw bytes." },
+    "contentType": { "type": "string", "description": "MIME type, e.g. \"application/pdf\". Defaults to application/octet-stream (or is inferred from the file extension / fetched response)." },
+    "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." }
+  }
+}