@mailkite/mcp 0.8.0 → 0.9.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.9.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.9.0"
   }
 }

package/spec/api.json

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