@mailkite/mcp 0.5.0 → 0.8.0

package/README.md

@@ -5,9 +5,14 @@
 (Claude Desktop, Claude Code, Cursor, …) as tools — send mail, manage domains,
 webhooks, routes, and inbound messages, all from a chat.
 
+> **Read-only mirror.** This repo is a generated, release-time mirror of the MailKite
+> monorepo (the private source of truth); the source isn't developed here. Install
+> `@mailkite/mcp` from npm rather than cloning, and see the docs at
+> <https://mailkite.dev/docs/libraries#mcp>.
+
 It's a **thin layer**. The tools, their input schemas, and validation all come
 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
+handling come from the [MailKite Node SDK](https://github.com/mailkite/mailkite-node). Nothing about the API is
 duplicated here — update the spec and the MCP follows.
 
 > ### Hosted vs local — which should I use?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.5.0",
+  "version": "0.8.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,12 @@
   "homepage": "https://mailkite.dev/docs/libraries",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mailkite/mailkite.git",
-    "directory": "sdks/mcp"
+    "url": "git+https://github.com/mailkite/mailkite-mcp.git"
   },
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.5.0"
+    "mailkite": "^0.8.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.8.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"
@@ -343,6 +343,233 @@
       ],
       "returns": "any"
     },
+    {
+      "name": "listLists",
+      "summary": "List your contact lists (static, curated broadcast audiences), each with its member count.",
+      "http": {
+        "method": "GET",
+        "path": "/api/lists"
+      },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "createList",
+      "summary": "Create a contact list. Returns the list with its id (lst_…); add contacts with addListContacts.",
+      "http": {
+        "method": "POST",
+        "path": "/api/lists"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-list-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "getList",
+      "summary": "Get one contact list with its member count.",
+      "http": {
+        "method": "GET",
+        "path": "/api/lists/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "updateList",
+      "summary": "Rename a contact list.",
+      "http": {
+        "method": "PATCH",
+        "path": "/api/lists/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "update-list-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "deleteList",
+      "summary": "Delete a contact list. The list is removed; the contacts themselves are kept.",
+      "http": {
+        "method": "DELETE",
+        "path": "/api/lists/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "listListContacts",
+      "summary": "List the contacts that are members of a list.",
+      "http": {
+        "method": "GET",
+        "path": "/api/lists/{id}/contacts"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "addListContacts",
+      "summary": "Add contacts (by id, ctr_…) to a list. Returns how many were newly added; contacts already on the list are ignored.",
+      "http": {
+        "method": "POST",
+        "path": "/api/lists/{id}/contacts"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "add-list-contacts-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "removeListContact",
+      "summary": "Remove one contact from a list (the contact itself is kept).",
+      "http": {
+        "method": "DELETE",
+        "path": "/api/lists/{id}/contacts/{contactId}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "contactId",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "listBroadcasts",
+      "summary": "List your broadcasts (one-to-many sends) with status and send stats.",
+      "http": {
+        "method": "GET",
+        "path": "/api/broadcasts"
+      },
+      "args": [],
+      "returns": "any"
+    },
+    {
+      "name": "createBroadcast",
+      "summary": "Create a broadcast draft. `from` is required; set `audience` to { type: \"all\" } or { type: \"list\", id: \"lst_…\" }. Returns the broadcast with its id (bct_…). Send it with sendBroadcast.",
+      "http": {
+        "method": "POST",
+        "path": "/api/broadcasts"
+      },
+      "args": [
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "create-broadcast-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "getBroadcast",
+      "summary": "Get one broadcast with its status and recipient summary.",
+      "http": {
+        "method": "GET",
+        "path": "/api/broadcasts/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "updateBroadcast",
+      "summary": "Edit a draft broadcast (any of from/subject/audience/html/… ). Drafts only.",
+      "http": {
+        "method": "PATCH",
+        "path": "/api/broadcasts/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "update-broadcast-request"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "deleteBroadcast",
+      "summary": "Delete a broadcast draft.",
+      "http": {
+        "method": "DELETE",
+        "path": "/api/broadcasts/{id}"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        }
+      ],
+      "returns": "any"
+    },
+    {
+      "name": "sendBroadcast",
+      "summary": "Send a broadcast now, or pass an ISO 8601 `scheduledAt` to schedule it. A one-click unsubscribe is always added. Returns the status and resolved audience count.",
+      "http": {
+        "method": "POST",
+        "path": "/api/broadcasts/{id}/send"
+      },
+      "args": [
+        {
+          "name": "id",
+          "in": "path"
+        },
+        {
+          "name": "body",
+          "in": "body",
+          "schema": "send-broadcast-request"
+        }
+      ],
+      "returns": "any",
+      "agentConfirm": true
+    },
     {
       "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.",
@@ -415,6 +642,21 @@
       ],
       "returns": "string",
       "sdkOnly": true
+    },
+    {
+      "name": "semanticSearch",
+      "summary": "Semantic search over the MailKite documentation — returns the most relevant doc sections for a natural-language query (hybrid vector + keyword search over https://mailkite.dev/docs). Public; no authentication required.",
+      "http": {
+        "method": "GET",
+        "path": "/v1/docs/search"
+      },
+      "args": [
+        {
+          "name": "query",
+          "in": "query"
+        }
+      ],
+      "returns": "semantic-search-response"
     }
   ]
 }

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",
@@ -655,13 +693,386 @@
         "ok": true
       }
     },
+    {
+      "name": "list_lists",
+      "method": "listLists",
+      "args": {},
+      "request": {
+        "method": "GET",
+        "path": "/api/lists"
+      },
+      "response": {
+        "status": 200,
+        "body": [
+          {
+            "id": "lst_1",
+            "name": "Beta testers",
+            "member_count": 2
+          }
+        ]
+      },
+      "result": [
+        {
+          "id": "lst_1",
+          "name": "Beta testers",
+          "member_count": 2
+        }
+      ]
+    },
+    {
+      "name": "create_list",
+      "method": "createList",
+      "args": {
+        "name": "Beta testers"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/lists",
+        "bodySchema": "create-list-request",
+        "body": {
+          "name": "Beta testers"
+        }
+      },
+      "response": {
+        "status": 201,
+        "body": {
+          "id": "lst_1",
+          "name": "Beta testers",
+          "member_count": 0
+        }
+      },
+      "result": {
+        "id": "lst_1",
+        "name": "Beta testers",
+        "member_count": 0
+      }
+    },
+    {
+      "name": "get_list",
+      "method": "getList",
+      "args": {
+        "id": "lst_1"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/api/lists/lst_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "lst_1",
+          "name": "Beta testers",
+          "member_count": 2
+        }
+      },
+      "result": {
+        "id": "lst_1",
+        "name": "Beta testers",
+        "member_count": 2
+      }
+    },
+    {
+      "name": "update_list",
+      "method": "updateList",
+      "args": {
+        "id": "lst_1",
+        "name": "VIPs"
+      },
+      "request": {
+        "method": "PATCH",
+        "path": "/api/lists/lst_1",
+        "bodySchema": "update-list-request",
+        "body": {
+          "name": "VIPs"
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "lst_1",
+          "name": "VIPs",
+          "member_count": 2
+        }
+      },
+      "result": {
+        "id": "lst_1",
+        "name": "VIPs",
+        "member_count": 2
+      }
+    },
+    {
+      "name": "delete_list",
+      "method": "deleteList",
+      "args": {
+        "id": "lst_1"
+      },
+      "request": {
+        "method": "DELETE",
+        "path": "/api/lists/lst_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "ok": true
+        }
+      },
+      "result": {
+        "ok": true
+      }
+    },
+    {
+      "name": "list_list_contacts",
+      "method": "listListContacts",
+      "args": {
+        "id": "lst_1"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/api/lists/lst_1/contacts"
+      },
+      "response": {
+        "status": 200,
+        "body": [
+          {
+            "id": "ctr_1",
+            "email": "jane@acme.com",
+            "name": "Jane Doe"
+          }
+        ]
+      },
+      "result": [
+        {
+          "id": "ctr_1",
+          "email": "jane@acme.com",
+          "name": "Jane Doe"
+        }
+      ]
+    },
+    {
+      "name": "add_list_contacts",
+      "method": "addListContacts",
+      "args": {
+        "id": "lst_1",
+        "contactIds": [
+          "ctr_1",
+          "ctr_2"
+        ]
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/lists/lst_1/contacts",
+        "bodySchema": "add-list-contacts-request",
+        "body": {
+          "contactIds": [
+            "ctr_1",
+            "ctr_2"
+          ]
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "added": 2
+        }
+      },
+      "result": {
+        "added": 2
+      }
+    },
+    {
+      "name": "remove_list_contact",
+      "method": "removeListContact",
+      "args": {
+        "id": "lst_1",
+        "contactId": "ctr_1"
+      },
+      "request": {
+        "method": "DELETE",
+        "path": "/api/lists/lst_1/contacts/ctr_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "ok": true
+        }
+      },
+      "result": {
+        "ok": true
+      }
+    },
+    {
+      "name": "list_broadcasts",
+      "method": "listBroadcasts",
+      "args": {},
+      "request": {
+        "method": "GET",
+        "path": "/api/broadcasts"
+      },
+      "response": {
+        "status": 200,
+        "body": [
+          {
+            "id": "bct_1",
+            "subject": "Launch week",
+            "status": "draft"
+          }
+        ]
+      },
+      "result": [
+        {
+          "id": "bct_1",
+          "subject": "Launch week",
+          "status": "draft"
+        }
+      ]
+    },
+    {
+      "name": "create_broadcast",
+      "method": "createBroadcast",
+      "args": {
+        "from": "news@app.mailkite.dev",
+        "subject": "Launch week",
+        "audience": {
+          "type": "all"
+        },
+        "html": "<h1>We shipped</h1>"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/broadcasts",
+        "bodySchema": "create-broadcast-request",
+        "body": {
+          "from": "news@app.mailkite.dev",
+          "subject": "Launch week",
+          "audience": {
+            "type": "all"
+          },
+          "html": "<h1>We shipped</h1>"
+        }
+      },
+      "response": {
+        "status": 201,
+        "body": {
+          "id": "bct_1",
+          "subject": "Launch week",
+          "status": "draft"
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "subject": "Launch week",
+        "status": "draft"
+      }
+    },
+    {
+      "name": "get_broadcast",
+      "method": "getBroadcast",
+      "args": {
+        "id": "bct_1"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/api/broadcasts/bct_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "bct_1",
+          "subject": "Launch week",
+          "status": "draft"
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "subject": "Launch week",
+        "status": "draft"
+      }
+    },
+    {
+      "name": "update_broadcast",
+      "method": "updateBroadcast",
+      "args": {
+        "id": "bct_1",
+        "subject": "Launch week (final)"
+      },
+      "request": {
+        "method": "PATCH",
+        "path": "/api/broadcasts/bct_1",
+        "bodySchema": "update-broadcast-request",
+        "body": {
+          "subject": "Launch week (final)"
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "bct_1",
+          "subject": "Launch week (final)",
+          "status": "draft"
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "subject": "Launch week (final)",
+        "status": "draft"
+      }
+    },
+    {
+      "name": "delete_broadcast",
+      "method": "deleteBroadcast",
+      "args": {
+        "id": "bct_1"
+      },
+      "request": {
+        "method": "DELETE",
+        "path": "/api/broadcasts/bct_1"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "ok": true
+        }
+      },
+      "result": {
+        "ok": true
+      }
+    },
+    {
+      "name": "send_broadcast",
+      "method": "sendBroadcast",
+      "args": {
+        "id": "bct_1",
+        "scheduledAt": "2026-07-01T15:00:00Z"
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/broadcasts/bct_1/send",
+        "bodySchema": "send-broadcast-request",
+        "body": {
+          "scheduledAt": "2026-07-01T15:00:00Z"
+        }
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "id": "bct_1",
+          "status": "scheduled",
+          "audienceCount": 2
+        }
+      },
+      "result": {
+        "id": "bct_1",
+        "status": "scheduled",
+        "audienceCount": 2
+      }
+    },
     {
       "name": "send_with_template",
       "method": "send",
       "args": {
         "from": "hello@app.mailkite.dev",
         "to": "ada@example.com",
-        "templateId": "base_welcome-dark",
+        "templateId": "base_welcome",
         "templateData": {
           "name": "Ada"
         }
@@ -673,7 +1084,7 @@
         "body": {
           "from": "hello@app.mailkite.dev",
           "to": "ada@example.com",
-          "templateId": "base_welcome-dark",
+          "templateId": "base_welcome",
           "templateData": {
             "name": "Ada"
           }
@@ -733,8 +1144,8 @@
         "status": 200,
         "body": [
           {
-            "id": "base_welcome-dark",
-            "name": "Welcome — Dark",
+            "id": "base_welcome",
+            "name": "Welcome",
             "category": "Welcome",
             "subject": "Welcome to MailKite",
             "is_base": 1
@@ -743,8 +1154,8 @@
       },
       "result": [
         {
-          "id": "base_welcome-dark",
-          "name": "Welcome — Dark",
+          "id": "base_welcome",
+          "name": "Welcome",
           "category": "Welcome",
           "subject": "Welcome to MailKite",
           "is_base": 1
@@ -779,7 +1190,7 @@
       "name": "create_template",
       "method": "createTemplate",
       "args": {
-        "baseId": "base_welcome-dark",
+        "baseId": "base_welcome",
         "name": "My Welcome"
       },
       "request": {
@@ -787,7 +1198,7 @@
         "path": "/api/templates",
         "bodySchema": "create-template-request",
         "body": {
-          "baseId": "base_welcome-dark",
+          "baseId": "base_welcome",
           "name": "My Welcome"
         }
       },
@@ -956,6 +1367,42 @@
         "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC9E2ll8K9E314m\njPfFkDBmImKFyvnqBJnqHukcAteqs99kK5QSx5wmg7PUw/9Ti/HTOr2V6lgXy6d+\nXbZl3XjCaFkmgTgKF9Zz8TtIQVUJNlmw1ztKEFr+yILoFovNxnND5WR+Nd5BUC6W\nW8sOAjswB21WthjDyVfEVSOHHRdYHcKAiF6e7yISDL5p9rcLFGjV37dvmH0DcskJ\nuYNwuAXlsEi4NIC3u4hK23pP9BEkDEmf0rmbSHugTl/VyzAlUiN/wUEcGu9Rl5iD\npIar+Vnbyr8ze6RNChWKcNjCZdGgI1mLDItbPEtW1IPvtyP6ymGuUqwl+C553q2t\nhuCURvlrAgMBAAECggEAWua+QXhZi28oQLh9VspfunrFizVuuYfEx75crE7hiPw5\nZltdMTouZIXlK2Gfm3coqDkRdMXZ3HbY6/P6ATddG3o3gj+VxaR4Qf20VqSyUV+D\n93VC1/TNCrkz1okgZaoHOJlMmzEizZvTCg7PrMh91DV957ZcaaSfQZD9J7RgyMeS\nC393/TI2IBR3nFQQMuNt0Rx0uXy2/T18hNQl2eSL+L2V+oCMERRetWzn9rQMDXI7\niLmh/dxE4gcTdSIflAUonWSFH6e9o8p+yJja4J966wP+B7j2dqmFr/09gBa3djHv\nEy+nhTYpfTrfYKnnE2pcXpFHWhd1iyRls93+Mb/RwQKBgQDqCyTLa8hjeeAun7fq\n2piRrFVr8NRVrFQwLmA8/3lcjXhCC80FG+SdSaZBJPD7EFDT3xePl/OnQmSHSnpR\nD+vklHVPAO4n3aMa/HKFgpxasxpUqRddzL6bBFNHpBgQR9Wv6hPiDP42SS7//uQF\nkrduS20kKsnrpGogy48zJQLfYwKBgQDO0E+PMmshHWbWDEE7Fjoe0dZtPx7CSG0B\nKXj5G+njHltUxPxodAYb95dUHQl/sFy3JpNcyBk8P+qlc/fhqojR/fE3+qK+EHjw\nKW/Ka4vEegtwdTXIeG4WgpTtFOjY7qsGHSFk2rFFjDrYtCMq6IBIClqk+dueCg52\nQsEHXQRwWQKBgQDBDNQa3xr5wswCaUhhdlImxsnnMU1UJcODwp0rc2d9ykuJ3wYL\n0sguXVO/pGMKFJk3Smu6zBH0wzT8y5g9SS7A6xwgQJoxVAZ3+gfUzLl/rwBnGNrn\nSj1mzJiNHXOj6jz+z8v6x9DgolkcW/lmB3E6jwjFrm3D62iHCKFkBIFsFQKBgAGq\ni/mLXnGV2w4+awge1bkJ18BpkcXe74Hi46aeIvRBelrke2QcCzCOfhmfYkQ1F4oi\nNW257vodSbariIO47AFFGnxo+Iave0n0C4KF+0pJ8W2mhBhpX/muc6S1VmrpAVe7\nRFmbqXH1/0NfsCjYVrA95R0PJkXPru4k+4kjprWBAoGAHtU/VXiOqSagIo3J/Bm5\nyUcJdbbguV/T9PPVu/Lq8SypCd5vqmwgYRmG+mIJEd/VYRkCZn3gbqNCn5OfbJh5\nG4Xatr7aofxyz2Qon/nix8Ut1+s1Npg1ugkz/atr4CZ4QArk8JmwsCReWJXCjKLX\n2WObKEWjGhgwths3MrC/CDw=\n-----END PRIVATE KEY-----"
       },
       "result": "Hello from MailKite — encrypted at rest. 🔒"
+    },
+    {
+      "name": "semantic_search",
+      "method": "semanticSearch",
+      "args": {
+        "query": "domains"
+      },
+      "request": {
+        "method": "GET",
+        "path": "/v1/docs/search"
+      },
+      "response": {
+        "status": 200,
+        "body": {
+          "query": "domains",
+          "matches": [
+            {
+              "slug": "domains",
+              "title": "Domains & DNS",
+              "section": "website",
+              "snippet": "Add a domain, set DNS, and verify."
+            }
+          ]
+        }
+      },
+      "result": {
+        "query": "domains",
+        "matches": [
+          {
+            "slug": "domains",
+            "title": "Domains & DNS",
+            "section": "website",
+            "snippet": "Add a domain, set DNS, and verify."
+          }
+        ]
+      }
     }
   ]
 }

package/spec/schemas/add-list-contacts-request.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "add-list-contacts-request",
+  "title": "Add contacts to list request body",
+  "type": "object",
+  "required": ["contactIds"],
+  "additionalProperties": false,
+  "properties": {
+    "contactIds": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/spec/schemas/create-broadcast-request.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-broadcast-request",
+  "title": "Create broadcast request body",
+  "type": "object",
+  "required": ["from"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "from": { "type": "string" },
+    "replyTo": { "type": "string" },
+    "subject": { "type": "string" },
+    "preview": { "type": "string" },
+    "audience": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["all", "list", "filter"] },
+        "id": { "type": "string" },
+        "query": { "type": "string" }
+      }
+    },
+    "templateId": { "type": "string" },
+    "html": { "type": "string" },
+    "text": { "type": "string" },
+    "footerAddress": { "type": "string" }
+  }
+}

package/spec/schemas/create-list-request.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-list-request",
+  "title": "Create list request body",
+  "type": "object",
+  "required": ["name"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" }
+  }
+}

package/spec/schemas/semantic-search-response.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "semantic-search-response",
+  "title": "Semantic docs search response",
+  "type": "object",
+  "required": ["query", "matches"],
+  "properties": {
+    "query": { "type": "string", "description": "The query that was searched." },
+    "matches": {
+      "type": "array",
+      "description": "Most-relevant documentation sections, best first.",
+      "items": {
+        "type": "object",
+        "required": ["slug", "title", "snippet"],
+        "properties": {
+          "slug": { "type": "string", "description": "Doc slug — the page lives at https://mailkite.dev/docs/<slug> (e.g. \"quickstart\", \"domains\")." },
+          "title": { "type": "string", "description": "Human page title." },
+          "section": { "type": "string", "description": "Doc section/category." },
+          "snippet": { "type": "string", "description": "A relevant excerpt from the matched section." },
+          "score": { "type": "number", "description": "Relevance score (higher is closer); absent for lexical-only matches." }
+        }
+      }
+    }
+  }
+}

package/spec/schemas/send-broadcast-request.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "send-broadcast-request",
+  "title": "Send broadcast request body",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "scheduledAt": { "type": "string" }
+  }
+}

package/spec/schemas/update-broadcast-request.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "update-broadcast-request",
+  "title": "Update broadcast request body (draft edits; all fields optional)",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "from": { "type": "string" },
+    "replyTo": { "type": "string" },
+    "subject": { "type": "string" },
+    "preview": { "type": "string" },
+    "audience": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "enum": ["all", "list", "filter"] },
+        "id": { "type": "string" },
+        "query": { "type": "string" }
+      }
+    },
+    "templateId": { "type": "string" },
+    "html": { "type": "string" },
+    "text": { "type": "string" },
+    "footerAddress": { "type": "string" }
+  }
+}

package/spec/schemas/update-list-request.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "update-list-request",
+  "title": "Update list request body",
+  "type": "object",
+  "required": ["name"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" }
+  }
+}

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],