@mailkite/mcp 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.9.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.9.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.9.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",