@mailkite/mcp 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.5.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.5.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.5.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": {
@@ -27,7 +27,7 @@
     },
     {
       "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.",
+      "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"

package/spec/cases.json

@@ -72,6 +72,44 @@
         "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",

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

@@ -2,13 +2,15 @@
   "$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",
-  "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." },
+    "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],