@mailkite/mcp 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailkite/mcp",
-  "version": "0.1.0",
+  "version": "0.2.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,13 @@
   "homepage": "https://mailkite.dev/docs/libraries",
   "repository": {
     "type": "git",
-    "url": "https://github.com/fijiwebdesign/mailkite.git",
+    "url": "git+https://github.com/fijiwebdesign/mailkite.git",
     "directory": "sdks/mcp"
   },
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
-    "mailkite": "^0.1.0"
+    "mailkite": "^0.2.0"
   }
 }

package/server.mjs

@@ -58,6 +58,9 @@ function buildInputSchema(method) {
     if (arg.in === "path") {
       properties[arg.name] = { type: "string", description: `Path parameter \`${arg.name}\`.` };
       required.push(arg.name);
+    } else if (arg.in === "query") {
+      properties[arg.name] = { type: "string", description: `Query parameter \`${arg.name}\`.` };
+      required.push(arg.name);
     } else if (arg.in === "body" && arg.schema && schemas[arg.schema]) {
       const body = schemas[arg.schema];
       Object.assign(properties, body.properties || {});
@@ -77,7 +80,11 @@ const credentialNote = (method) => {
 
 const tools = api.methods.map((method) => ({
   name: toolName(method),
-  description: `${method.summary} ${credentialNote(method)}`,
+  description: `${method.summary} ${credentialNote(method)}${
+    method.agentConfirm
+      ? " Does NOT register automatically — returns a dashboard link for the user to review the price and confirm. An assistant can never purchase a domain on its own."
+      : ""
+  }`,
   inputSchema: buildInputSchema(method),
   _method: method, // kept server-side for dispatch; not sent to the client
 }));
@@ -94,16 +101,22 @@ function resolveCall(method, input) {
   input = input || {};
   let urlPath = method.http.path;
   let bodySchemaId = null;
+  const query = [];
 
   for (const arg of method.args || []) {
     if (arg.in === "path") {
       const value = input[arg.name];
       if (value == null || value === "") throw new Error(`Missing required path parameter: ${arg.name}`);
       urlPath = urlPath.replace(`{${arg.name}}`, encodeURIComponent(String(value)));
+    } else if (arg.in === "query") {
+      const value = input[arg.name];
+      if (value == null || value === "") throw new Error(`Missing required query parameter: ${arg.name}`);
+      query.push(`${encodeURIComponent(arg.name)}=${encodeURIComponent(String(value))}`);
     } else if (arg.in === "body" && arg.schema) {
       bodySchemaId = arg.schema;
     }
   }
+  if (query.length) urlPath += (urlPath.includes("?") ? "&" : "?") + query.join("&");
 
   let body;
   if (bodySchemaId) {
@@ -163,6 +176,25 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     }
   }
 
+  // Gated methods (e.g. domain registration) must be approved by a human and are never run
+  // automatically by an AI agent. Return the dashboard URL to confirm instead of calling the API.
+  if (tool._method.agentConfirm) {
+    const dash = (process.env.MAILKITE_DASHBOARD_URL || "https://app.mailkite.dev").replace(/\/+$/, "");
+    const domain = (req.params.arguments && req.params.arguments.domain) || "the domain";
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Domain registration can't be completed automatically — it has to be approved by you.\n\n` +
+            `Open the dashboard to review the price and confirm the purchase of ${domain}:\n` +
+            `${dash}/domains\n\n` +
+            `Once it's registered there, tell me to continue.`,
+        },
+      ],
+    };
+  }
+
   if (!apiKey) {
     return {
       isError: true,

package/spec/api.json

@@ -1,6 +1,6 @@
 {
   "name": "mailkite",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -75,6 +75,21 @@
       "args": [{ "name": "id", "in": "path" }],
       "returns": "any"
     },
+    {
+      "name": "checkDomainAvailability",
+      "summary": "Check whether a domain is available to register, and at what price. Read-only — no charge.",
+      "http": { "method": "GET", "path": "/api/domains/register/check" },
+      "args": [{ "name": "domain", "in": "query" }],
+      "returns": "any"
+    },
+    {
+      "name": "registerDomain",
+      "summary": "Register (buy) a domain on the customer's behalf; provisions mail DNS and adds it to the account in one call. Charges the registrar.",
+      "http": { "method": "POST", "path": "/api/domains/register" },
+      "args": [{ "name": "body", "in": "body", "schema": "register-domain-request" }],
+      "returns": "any",
+      "agentConfirm": true
+    },
     {
       "name": "listRoutes",
       "summary": "List inbound routing rules.",

package/spec/cases.json

@@ -122,6 +122,81 @@
       "response": { "status": 200, "body": { "ok": true } },
       "result": { "ok": true }
     },
+    {
+      "name": "check_domain_availability",
+      "method": "checkDomainAvailability",
+      "args": { "domain": "acme.com" },
+      "request": { "method": "GET", "path": "/api/domains/register/check" },
+      "response": {
+        "status": 200,
+        "body": {
+          "configured": true,
+          "domain": "acme.com",
+          "available": true,
+          "premium": false,
+          "price": { "amount": 12.99, "currency": "USD", "period": 1, "periodUnit": "y" }
+        }
+      },
+      "result": {
+        "configured": true,
+        "domain": "acme.com",
+        "available": true,
+        "premium": false,
+        "price": { "amount": 12.99, "currency": "USD", "period": 1, "periodUnit": "y" }
+      }
+    },
+    {
+      "name": "register_domain",
+      "method": "registerDomain",
+      "args": {
+        "domain": "acme.com",
+        "contact": {
+          "firstName": "Jane",
+          "lastName": "Doe",
+          "email": "jane@example.com",
+          "phone": "+1.4155551234",
+          "address": "123 Main St",
+          "city": "SF",
+          "zip": "94016",
+          "country": "US"
+        },
+        "years": 1
+      },
+      "request": {
+        "method": "POST",
+        "path": "/api/domains/register",
+        "bodySchema": "register-domain-request",
+        "body": {
+          "domain": "acme.com",
+          "contact": {
+            "firstName": "Jane",
+            "lastName": "Doe",
+            "email": "jane@example.com",
+            "phone": "+1.4155551234",
+            "address": "123 Main St",
+            "city": "SF",
+            "zip": "94016",
+            "country": "US"
+          },
+          "years": 1
+        }
+      },
+      "response": {
+        "status": 201,
+        "body": {
+          "domain": { "id": "dom_1", "domain": "acme.com", "status": "verified" },
+          "dns": [],
+          "registration": { "status": "registered", "reference": "ref_1" },
+          "dnsProvisioned": true
+        }
+      },
+      "result": {
+        "domain": { "id": "dom_1", "domain": "acme.com", "status": "verified" },
+        "dns": [],
+        "registration": { "status": "registered", "reference": "ref_1" },
+        "dnsProvisioned": true
+      }
+    },
     {
       "name": "list_routes",
       "method": "listRoutes",

package/spec/schemas/register-domain-request.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "register-domain-request",
+  "title": "Register domain request body",
+  "type": "object",
+  "required": ["domain", "contact"],
+  "additionalProperties": false,
+  "properties": {
+    "domain": { "type": "string" },
+    "contact": {
+      "type": "object",
+      "required": [
+        "firstName",
+        "lastName",
+        "email",
+        "phone",
+        "address",
+        "city",
+        "zip",
+        "country"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "firstName": { "type": "string" },
+        "lastName": { "type": "string" },
+        "email": { "type": "string" },
+        "phone": { "type": "string", "description": "E.164-ish, +<cc>.<number>, e.g. +1.4155551234" },
+        "address": { "type": "string" },
+        "city": { "type": "string" },
+        "zip": { "type": "string" },
+        "country": { "type": "string", "description": "ISO 3166-1 alpha-2, e.g. US" },
+        "state": { "type": "string", "description": "ISO 3166-2 subdivision, e.g. US-CA" },
+        "organization": { "type": "string" },
+        "type": { "type": "string", "enum": ["individual", "company", "association", "publicbody"] }
+      }
+    },
+    "years": { "type": "integer", "minimum": 1 },
+    "dryRun": { "type": "boolean" }
+  }
+}