@mailkite/mcp 0.8.0 → 0.10.0

package/README.md

@@ -1,38 +1,30 @@
-# @mailkite/mcp
-
-[Model Context Protocol](https://modelcontextprotocol.io) server for
-[MailKite](https://mailkite.dev). It exposes the MailKite API to LLM agents
-(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](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?
->
-> 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
-token is the same one the SDKs take: an `mk_live_…` API key (for sending) or a
-management session token.
+<p align="center">
+  <a href="https://mailkite.dev">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://mailkite.dev/brand/logo-email-dark.png">
+      <img src="https://mailkite.dev/brand/logo-email.png" alt="MailKite" height="56">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">@mailkite/mcp</h1>
+
+<p align="center">
+  <b>Email for every product you ship</b> — receive email as a webhook, send over a verified domain, give an AI agent its own inbox.
+  <br>The official <a href="https://mailkite.dev">MailKite</a> library for AI agents (MCP).
+</p>
+
+<p align="center">
+  <a href="https://mailkite.dev/docs">Docs</a> ·
+  <a href="https://mailkite.dev/docs/libraries#mcp">Library guide</a> ·
+  <a href="https://mailkite.dev">mailkite.dev</a> ·
+  <a href="https://mailkite.dev/docs/ai-agents">AI agents</a>
+</p>
+<p align="center"><a href="https://www.npmjs.com/package/@mailkite/mcp"><img src="https://img.shields.io/npm/v/@mailkite/mcp?color=2563eb&label=npm" alt="npm"></a></p>
+
+> **Read-only mirror.** This repo is a generated, release-time mirror of the MailKite monorepo (the private source of truth) — development doesn't happen here. Install from npm and open issues against the [MailKite docs](https://mailkite.dev/docs).
+
+## Install
 
 ```json
 {
@@ -46,63 +38,63 @@ management session token.
 }
 ```
 
-| Env var | Required | Default | Notes |
-| --- | --- | --- | --- |
-| `MAILKITE_API_KEY` | yes | — | Bearer credential (`mk_live_…` API key or session token) |
-| `MAILKITE_BASE_URL` | no | `https://api.mailkite.dev` | Override for local/staging |
-
 ## Tools
 
-One tool per MailKite API operation (generated from [`../spec/api.json`](../spec/api.json)):
-
-| 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 |
-| `mailkite_delete_domain` | Remove a domain |
-| `mailkite_verify_domain` | Check DNS and update status |
-| `mailkite_set_webhook` | Set/replace the domain catch-all webhook |
-| `mailkite_delete_webhook` | Remove the domain webhook |
-| `mailkite_test_webhook` | Send a signed test event to the webhook |
-| `mailkite_list_routes` | List inbound routing rules |
-| `mailkite_create_route` | Create a route (match, action, destination) |
-| `mailkite_list_messages` | List stored messages |
-| `mailkite_get_message` | Get a message with deliveries + attachments |
-| `mailkite_retry_delivery` | Re-deliver a stored message to its webhook |
-| `mailkite_verify_webhook` | Verify an `x-mailkite-signature` header (local — no API call) |
-
-`mailkite_verify_webhook` is a **local** tool: it runs the SDK's `verifyWebhook`
-in-process (no credential, no network) and returns `{ "valid": true | false }`.
-Every other tool is one MailKite API operation.
-
-Each tool's input is a flat object with the real field names (e.g.
-`mailkite_send` takes `from`, `to`, `subject`, `html`, `text`, …). Required
-fields and types are enforced with [`ajv`](https://ajv.js.org) against the same
-JSON Schemas in [`../spec/schemas`](../spec/schemas) that the SDKs and
-conformance harness use — invalid calls are rejected before any HTTP request.
-
-## How it works
+One tool per MailKite API method, generated from the shared contract — including `mailkite_send`, `mailkite_semantic_search`, `mailkite_agent`, domain/route/webhook management, and more. Full list + schemas: **https://mailkite.dev/docs/libraries#mcp**.
 
-```
-api.json  ──▶  one MCP tool per method (name, description, input schema)
-schemas/* ──▶  ajv validators (validate the call before dispatch)
-Node SDK  ──▶  MailKite.request(method, path, body)  (auth, HTTP, errors)
-              local methods (verifyWebhook) dispatch in-process — no HTTP
-```
+## Use it from an AI agent — MCP + Agent connectors
 
-See [`PLAN.md`](./PLAN.md) for the full design.
+MailKite speaks the [Model Context Protocol](https://modelcontextprotocol.io): every API method is a tool your AI assistant (Claude, Cursor, …) can call — send mail, manage domains, search the docs, and give an agent its own inbox. Full guide: **[https://mailkite.dev/docs/ai-agents](https://mailkite.dev/docs/ai-agents)**.
 
-## Develop
+**Hosted (recommended) — one-click OAuth, no key to copy:**
 
 ```bash
-npm install
-npm test        # boots the server over stdio, lists tools, checks validation + wire bytes
+claude mcp add --transport http mailkite https://mcp.mailkite.dev/mcp
+```
+
+In Claude Code you can also install the plugin:
+
+```text
+/plugin marketplace add mailkite/claude-code
+/plugin install mailkite@mailkite
 ```
 
-## License
+Any chat/UI agent: *"Add the MCP server at https://mcp.mailkite.dev/mcp and authenticate in the browser when prompted."*
+
+**Local (static key, offline / CI):**
+
+```json
+{ "mcpServers": { "mailkite": { "command": "npx", "args": ["-y", "@mailkite/mcp"], "env": { "MAILKITE_API_KEY": "mk_live_…" } } } }
+```
 
-MIT
+**Give an agent its own inbox.** Route inbound mail to a built-in **inbox agent** (the `agent` route action) and it answers, files, or escalates on its own — see [https://mailkite.dev/docs/ai-agents](https://mailkite.dev/docs/ai-agents).
+
+## All MailKite libraries
+
+Same contract, every language — pick the one for your stack (full list: [https://mailkite.dev/docs/libraries](https://mailkite.dev/docs/libraries)):
+
+| Library | Repo | Distribution |
+| --- | --- | --- |
+| MailKite for Node.js | [`mailkite-node`](https://github.com/mailkite/mailkite-node) | npm |
+| MailKite for Python | [`mailkite-python`](https://github.com/mailkite/mailkite-python) | PyPI |
+| MailKite for Ruby | [`mailkite-ruby`](https://github.com/mailkite/mailkite-ruby) | RubyGems |
+| MailKite for Java | [`mailkite-java`](https://github.com/mailkite/mailkite-java) | Maven Central |
+| MailKite for PHP | [`mailkite-php`](https://github.com/mailkite/mailkite-php) | Packagist |
+| MailKite for Go | [`mailkite-go`](https://github.com/mailkite/mailkite-go) | Go modules |
+| @mailkite/cli | [`mailkite-cli`](https://github.com/mailkite/mailkite-cli) | npm |
+| @mailkite/mcp **(this repo)** | [`mailkite-mcp`](https://github.com/mailkite/mailkite-mcp) | npm |
+| @mailkite/client | [`mailkite-js`](https://github.com/mailkite/mailkite-js) | npm |
+| @mailkite/expo | [`mailkite-expo`](https://github.com/mailkite/mailkite-expo) | npm |
+| MailKiteClient | [`mailkite-swift`](https://github.com/mailkite/mailkite-swift) | Swift Package Manager |
+| dev.mailkite:mailkite-client | [`mailkite-kotlin`](https://github.com/mailkite/mailkite-kotlin) | Maven Central |
+| mailkite_client | [`mailkite-flutter`](https://github.com/mailkite/mailkite-flutter) | pub.dev |
+
+## Docs & links
+
+- 📚 **Documentation:** https://mailkite.dev/docs
+- 📦 **This library's guide:** https://mailkite.dev/docs/libraries#mcp
+- 🤖 **AI agents (MCP + inbox agents):** https://mailkite.dev/docs/ai-agents
+- 🌐 **Website:** https://mailkite.dev
+- 🧭 **All libraries:** https://mailkite.dev/docs/libraries
+
+<sub>Generated from the shared MailKite API contract. © MailKite.</sub>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.8.0",
+  "version": "0.10.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": {
@@ -40,6 +40,6 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.8.0"
+    "mailkite": "^0.10.0"
   }
 }

package/spec/TODO.md

@@ -0,0 +1,36 @@
+# Spec TODO — propagate pending changes
+
+Visible checklist for spec changes that are **documented in `api.json` but not yet fully
+propagated** to the hand-written SDKs / plugin / registries. Clear an item once it ships.
+
+## `listMessages` + `listListContacts` — optional `before` / `limit` paging
+
+**Status (2026-06-28):** documented in `api.json` (method `summary` + a structured
+`optionalQuery` field) and live on the API (`GET /api/messages`, `GET /api/lists/:id/contacts`
+honor `before`/`limit`; response stays a **bare array**, default = pre-pagination behavior).
+
+### ✅ Done
+
+- [x] All **6 server SDKs** expose optional `before`/`limit` (idiomatic per language: positional
+      optional in node/python/ruby/php, boxed-nullable overloads in java, functional options
+      `mailkite.Before()/Limit()` in go). Backward compatible — no-arg calls unchanged.
+- [x] Each conformance runner forwards them + `cases.json` exercises real values;
+      `cd sdks/conformance && node run.mjs` → **55/55 across all 6**.
+- [x] **CLI** `messages list --before --limit`.
+- [x] SDK docs regenerated (`node sdks/scripts/build-sdk-docs.mjs`) — server-SDK method pages list
+      the optional params (client libs intentionally skipped; they don't expose them, see below).
+
+### ⏳ Still deferred (kept optional + low-value / blocked)
+
+These need optional-query-param support that doesn't exist yet, and the API tree is mid-refactor
+(another agent), so the hosted-MCP redeploy is held.
+
+- [ ] Add optional-query support to `sdks/clients/codegen.mjs` so the **4 client libs**
+      (TS/Kotlin/Flutter/Swift) emit `before?`/`limit?`, then regen.
+- [ ] Both MCP servers expose them as **optional** tool inputs — needs `tools.ts` +
+      `sdks/mcp/server.mjs` to stop forcing `in:"query"` args into `required`. Hosted MCP also
+      needs `cd api && npm run deploy` from a clean tree.
+- [ ] Claude Code **plugin** (`plugin/`) refresh if it pins tool schemas.
+
+> Until those land, MCP/client-lib users reach `before`/`limit` via the low-level `request()`
+> escape hatch (`GET /api/messages?before=…&limit=…`).

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.8.0",
+  "version": "0.10.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": {
@@ -305,12 +305,16 @@
     },
     {
       "name": "listMessages",
-      "summary": "List stored messages.",
+      "summary": "List stored messages, newest first. Optionally page with `before` (a `received_at` cursor) and `limit`; omit both for the default newest 100. Response is a bare array — paginate by passing the last row's `received_at` as the next `before`.",
       "http": {
         "method": "GET",
         "path": "/api/messages"
       },
       "args": [],
+      "optionalQuery": [
+        { "name": "before", "type": "integer", "description": "Cursor: return only messages with `received_at` strictly less than this (epoch ms). Omit for the first page." },
+        { "name": "limit", "type": "integer", "description": "Max rows to return, 1–200. Omitted = newest 100 (the pre-pagination default)." }
+      ],
       "returns": "any"
     },
     {
@@ -421,7 +425,7 @@
     },
     {
       "name": "listListContacts",
-      "summary": "List the contacts that are members of a list.",
+      "summary": "List the contacts that are members of a list, newest first. Optionally page with `before` (a `last_seen_at`/`created_at` cursor) and `limit`. Response is a bare array — paginate by passing the last row's `last_seen_at` (or `created_at`) as the next `before`.",
       "http": {
         "method": "GET",
         "path": "/api/lists/{id}/contacts"
@@ -432,6 +436,10 @@
           "in": "path"
         }
       ],
+      "optionalQuery": [
+        { "name": "before", "type": "integer", "description": "Cursor: return only members with `last_seen_at` (or `created_at`) strictly less than this (epoch ms). Omit for the first page." },
+        { "name": "limit", "type": "integer", "description": "Max rows to return (default 100, max 500)." }
+      ],
       "returns": "any"
     },
     {

package/spec/cases.json

@@ -630,7 +630,10 @@
     {
       "name": "list_messages",
       "method": "listMessages",
-      "args": {},
+      "args": {
+        "before": 1717000000000,
+        "limit": 50
+      },
       "request": {
         "method": "GET",
         "path": "/api/messages"
@@ -824,7 +827,9 @@
       "name": "list_list_contacts",
       "method": "listListContacts",
       "args": {
-        "id": "lst_1"
+        "id": "lst_1",
+        "before": 1717000000000,
+        "limit": 25
       },
       "request": {
         "method": "GET",