@mailkite/mcp 0.2.0 → 0.4.0

package/spec/check-docs.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// check-docs — validate that the website docs match our request SCHEMAS.
+//
+// "Our schema" = sdks/spec/schemas/*.json (the JSON Schemas every SDK + the MCP
+// server validate against). The website docs (website/src/pages/docs/*.astro)
+// are hand-written, so their field tables and request examples can drift from
+// the schema. This script is the agent-runnable guard: run it, read the report.
+//
+//   node sdks/spec/check-docs.mjs        # human/agent: prints ✓/✗, exits 1 on drift
+//   import { runChecks } from './check-docs.mjs'   # CI: see api/test/docs-schema.test.ts
+//
+// It checks, per schema-backed operation:
+//   1. the doc "Request fields" table lists exactly the schema's properties,
+//      with the same required set;
+//   2. every JSON request example in the docs uses only schema fields and
+//      includes the required ones;
+//   3. the SDK code samples include the required fields and use no wrong alias.
+// ---------------------------------------------------------------------------
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SPEC_DIR = dirname(fileURLToPath(import.meta.url)); // sdks/spec
+const ROOT = resolve(SPEC_DIR, '../..'); // repo root
+const read = (p) => readFileSync(p, 'utf8');
+const readJson = (p) => JSON.parse(read(p));
+
+const DOCS_DIR = resolve(ROOT, 'website/src/pages/docs');
+const docText = Object.fromEntries(
+  readdirSync(DOCS_DIR)
+    .filter((f) => f.endsWith('.astro'))
+    .map((f) => [f, read(resolve(DOCS_DIR, f))]),
+);
+const samplesTs = read(resolve(ROOT, 'website/src/lib/samples.ts'));
+
+const schema = (name) => readJson(resolve(SPEC_DIR, 'schemas', `${name}.json`));
+const eqSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+
+// ---- helpers --------------------------------------------------------------
+
+// All quoted keys (`"key":`) inside a JSON-ish block — includes nested keys,
+// which is what we want (attachment sub-fields are valid send fields).
+const jsonKeys = (block) => new Set([...block.matchAll(/"([a-zA-Z]+)"\s*:/g)].map((m) => m[1]));
+
+// Every backtick template literal in a file (docs put JSON examples in these).
+const templateLiterals = (src) => [...src.matchAll(/`([^`]*)`/g)].map((m) => m[1]);
+
+// ---- the checks -----------------------------------------------------------
+
+// Each entry ties a doc-visible operation to its schema + how to spot its
+// request examples among the docs' JSON blocks.
+const OPS = [
+  {
+    label: 'send',
+    schema: 'send-request',
+    // The "Request fields" table lives in sending.astro under this heading.
+    fieldTable: { file: 'sending.astro', heading: 'Request fields' },
+    // A send body has from+subject. Exclude inbound webhook payloads (which also
+    // carry from/subject but add type/auth/threadId) and responses (status).
+    isRequestExample: (k) =>
+      k.has('from') &&
+      k.has('subject') &&
+      !k.has('status') &&
+      !k.has('type') &&
+      !k.has('auth') &&
+      !k.has('threadId'),
+    nestedSchemaKeys: ['filename', 'url', 'content', 'contentType'], // attachments[].*
+    sample: { source: samplesTs, slice: ['sendSamples', 'initSamples'] },
+    wrongAliases: ['reply_to', 'in_reply_to', 'html_body', 'text_body', 'from_addr', 'to_addr'],
+  },
+  {
+    label: 'createRoute',
+    schema: 'create-route-request',
+    isRequestExample: (k) => k.has('match') && k.has('action'),
+  },
+  {
+    label: 'createDomain',
+    schema: 'create-domain-request',
+    isRequestExample: (k) => k.has('domain') && k.size <= 2,
+  },
+];
+
+function runChecks() {
+  const results = [];
+  const ok = (name) => results.push({ name, ok: true });
+  const fail = (name, detail) => results.push({ name, ok: false, detail });
+
+  for (const op of OPS) {
+    const s = schema(op.schema);
+    const props = new Set(Object.keys(s.properties));
+    const required = new Set(s.required ?? []);
+    const allowed = new Set([...props, ...(op.nestedSchemaKeys ?? [])]);
+
+    // ── Check 1: the "Request fields" table mirrors the schema exactly ──────
+    if (op.fieldTable) {
+      const src = docText[op.fieldTable.file] ?? '';
+      const table = src.match(
+        new RegExp(`<h2>${op.fieldTable.heading}</h2>([\\s\\S]*?)</table>`),
+      );
+      if (!table) {
+        fail(`${op.label}: fields table present`, `no "${op.fieldTable.heading}" table in ${op.fieldTable.file}`);
+      } else {
+        const docFields = new Set();
+        const docRequired = new Set();
+        for (const row of table[1].matchAll(/<tr>([\s\S]*?)<\/tr>/g)) {
+          const firstCell = row[1].match(/<td>([\s\S]*?)<\/td>/);
+          if (!firstCell) continue; // header row (uses <th>)
+          const names = [...firstCell[1].matchAll(/<code>([a-zA-Z]+)<\/code>/g)].map((m) => m[1]);
+          const isRequired = /Required\./.test(row[1]);
+          for (const n of names) {
+            docFields.add(n);
+            if (isRequired) docRequired.add(n);
+          }
+        }
+        if (eqSet(docFields, props)) ok(`${op.label}: fields table = schema properties`);
+        else
+          fail(
+            `${op.label}: fields table = schema properties`,
+            `table=${[...docFields].sort()} schema=${[...props].sort()}`,
+          );
+        if (eqSet(docRequired, required)) ok(`${op.label}: fields table required = schema required`);
+        else
+          fail(
+            `${op.label}: fields table required = schema required`,
+            `table=${[...docRequired].sort()} schema=${[...required].sort()}`,
+          );
+      }
+    }
+
+    // ── Check 2: every JSON request example uses only schema fields ─────────
+    let examplesSeen = 0;
+    for (const [file, src] of Object.entries(docText)) {
+      for (const block of templateLiterals(src)) {
+        const keys = jsonKeys(block);
+        if (keys.size === 0 || !op.isRequestExample(keys)) continue;
+        examplesSeen++;
+        const unknown = [...keys].filter((k) => !allowed.has(k));
+        if (unknown.length)
+          fail(`${op.label}: JSON example fields ⊆ schema (${file})`, `unknown: ${unknown}`);
+        const missing = [...required].filter((r) => !keys.has(r));
+        if (missing.length)
+          fail(`${op.label}: JSON example has required fields (${file})`, `missing: ${missing}`);
+      }
+    }
+    if (examplesSeen) ok(`${op.label}: ${examplesSeen} JSON request example(s) validated`);
+
+    // ── Check 3: SDK code samples include required fields, no wrong aliases ──
+    if (op.sample) {
+      // Pull each named sample object's body out of samples.ts.
+      for (const name of op.sample.slice) {
+        const m = op.sample.source.match(new RegExp(`export const ${name}[\\s\\S]*?\\n};`));
+        if (!m) continue;
+        const body = m[0].toLowerCase();
+        for (const alias of op.wrongAliases ?? []) {
+          if (body.includes(alias))
+            fail(`${op.label}: sample uses wrong alias (${name})`, `found "${alias}" — use the schema field`);
+        }
+      }
+    }
+  }
+  return results;
+}
+
+// ---- CLI ------------------------------------------------------------------
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const results = runChecks();
+  const failures = results.filter((r) => !r.ok);
+  for (const r of results) {
+    console.log(`${r.ok ? '✓' : '✗'} ${r.name}${r.detail ? `\n    ${r.detail}` : ''}`);
+  }
+  console.log(`\n${results.length - failures.length}/${results.length} checks passed.`);
+  if (failures.length) {
+    console.error(`\n${failures.length} doc/schema mismatch(es) — fix the .astro doc or the schema.`);
+    process.exit(1);
+  }
+}
+
+export { runChecks };

package/spec/schemas/agent-request.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "agent-request",
+  "title": "Send-to-agent request body",
+  "type": "object",
+  "required": ["text"],
+  "additionalProperties": false,
+  "properties": {
+    "text": { "type": "string", "description": "The message for the agent — it reads this as the incoming email body and decides what to do." },
+    "subject": { "type": "string", "description": "Optional subject line the agent sees on the message." },
+    "from": { "type": "string", "description": "Optional sender address the agent sees as the originator. Defaults to the account's API caller address." },
+    "html": { "type": "string", "description": "Optional HTML body. `text` is still required — the agent reasons over the plain-text content." },
+    "routeId": { "type": "string", "description": "Target a specific agent by its route id (rte_…). Omit to use the account's default agent (its most recently created agent route)." },
+    "address": { "type": "string", "description": "Target the agent whose route matches this address. Alternative to routeId." },
+    "model": { "type": "string", "description": "Override the model the agent runs on for this call (e.g. claude-sonnet-4-6)." }
+  }
+}

package/spec/schemas/agent-response.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "agent-response",
+  "title": "Send-to-agent response body",
+  "type": "object",
+  "required": ["ok"],
+  "properties": {
+    "ok": { "type": "boolean", "description": "Whether the agent ran to completion." },
+    "text": { "type": "string", "description": "The agent's reply — its final message after running." },
+    "messageId": { "type": "string", "description": "Id of the stored message the agent processed (msg_…)." },
+    "error": { "type": "string", "description": "Error detail when `ok` is false." }
+  }
+}

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

@@ -3,11 +3,16 @@
   "$id": "create-route-request",
   "title": "Create route request body",
   "type": "object",
-  "required": ["match", "action", "destination"],
+  "required": ["match"],
   "additionalProperties": false,
   "properties": {
-    "match": { "type": "string" },
-    "action": { "type": "string" },
-    "destination": { "type": "string" }
+    "match": { "type": "string", "description": "Address pattern: exact, *@domain, addr+*@domain, or /regex/." },
+    "action": {
+      "type": "string",
+      "enum": ["webhook", "forward", "store", "drop", "agent"],
+      "description": "What to do with matching mail. Defaults to webhook."
+    },
+    "destination": { "type": "string", "description": "Required for action webhook (URL) or forward (address)." },
+    "agentPrompt": { "type": "string", "description": "Required for action agent — instructions for the inbox agent." }
   }
 }

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

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "create-template-request",
+  "title": "Create template request body",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "baseId": { "type": "string", "description": "Clone this base template (base_…) into your own. When set, name is optional (defaults to the base's name)." },
+    "name": { "type": "string", "description": "Template name. Required unless baseId is given." },
+    "subject": { "type": "string", "description": "Default subject line for sends." },
+    "html": { "type": "string", "description": "Rendered, send-ready HTML." },
+    "text": { "type": "string", "description": "Plaintext fallback." },
+    "json": { "type": "string", "description": "Editor (TipTap) JSON source, for re-editing in the dashboard." },
+    "theme": { "type": "string", "description": "Brand tokens JSON (bg, surface, primary, text, logo, …)." }
+  }
+}

package/spec/schemas/decrypt-request.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "decrypt-request",
+  "title": "Decrypt request",
+  "description": "Inputs to decrypt — a local hybrid-envelope decryption, no API call.",
+  "type": "object",
+  "required": ["envelope", "privateKey"],
+  "additionalProperties": false,
+  "properties": {
+    "envelope": {
+      "type": "string",
+      "description": "The at-rest envelope JSON string ({v,keyAlg,fp,enc,iv,wrappedKey,ciphertext}) from MailKite."
+    },
+    "privateKey": {
+      "type": "string",
+      "description": "Your RSA private key in PKCS8/PEM form (-----BEGIN PRIVATE KEY-----) — the match to the public key the envelope was wrapped to."
+    }
+  }
+}

package/spec/schemas/encrypt-request.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "encrypt-request",
+  "title": "Encrypt request",
+  "description": "Inputs to encrypt — a local hybrid-envelope encryption, no API call.",
+  "type": "object",
+  "required": ["plaintext", "publicKey"],
+  "additionalProperties": false,
+  "properties": {
+    "plaintext": {
+      "type": "string",
+      "description": "The UTF-8 string to encrypt (e.g. a message body you're about to store)."
+    },
+    "publicKey": {
+      "type": "string",
+      "description": "The recipient domain's RSA public key in SPKI/PEM form (-----BEGIN PUBLIC KEY-----), ≥2048-bit."
+    }
+  }
+}

package/spec/schemas/route-message-request.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "route-message-request",
+  "title": "Route-message request body",
+  "type": "object",
+  "required": ["from"],
+  "additionalProperties": false,
+  "anyOf": [{ "required": ["routeId"] }, { "required": ["address"] }],
+  "properties": {
+    "routeId": { "type": "string", "description": "Target route by id (rte_…). One of routeId or address is required. The route must already be registered on this account." },
+    "address": { "type": "string", "description": "Target route by the address it matches. One of routeId or address is required." },
+    "from": { "type": "string", "description": "Sender address recorded on the message." },
+    "subject": { "type": "string", "description": "Optional subject line." },
+    "text": { "type": "string", "description": "Plain-text body." },
+    "html": { "type": "string", "description": "HTML body." }
+  }
+}

package/spec/schemas/route-response.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "route-response",
+  "title": "Route-message response body",
+  "type": "object",
+  "required": ["id", "routed", "action"],
+  "properties": {
+    "id": { "type": "string", "description": "Stored message id (msg_…)." },
+    "routed": { "type": "boolean", "description": "Whether the message was handed to the route's action." },
+    "action": { "type": "string", "description": "The action the matched route performed: webhook, forward, agent, store, or drop." }
+  }
+}

package/spec/schemas/send-request.json

@@ -3,7 +3,7 @@
   "$id": "send-request",
   "title": "Send request body",
   "type": "object",
-  "required": ["from", "to", "subject"],
+  "required": ["from", "to"],
   "additionalProperties": false,
   "properties": {
     "from": { "type": "string", "description": "An address on a verified domain." },
@@ -14,9 +14,18 @@
         { "type": "array", "items": { "type": "string" }, "minItems": 1 }
       ]
     },
-    "subject": { "type": "string" },
+    "subject": { "type": "string", "description": "Required unless supplied by a template." },
     "html": { "type": "string" },
     "text": { "type": "string" },
+    "templateId": {
+      "type": "string",
+      "description": "Send using a saved template — a user template (tpl_…) or a base template (base_…). Its subject/html/text seed the message; explicit subject/html/text here override them."
+    },
+    "templateData": {
+      "type": "object",
+      "description": "Values substituted into the template's {{merge_tags}} (e.g. {\"name\":\"Ann\"} fills {{name}}). HTML values are auto-escaped.",
+      "additionalProperties": { "type": ["string", "number", "boolean", "null"] }
+    },
     "cc": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
     "bcc": { "oneOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] },
     "replyTo": { "type": "string" },