apimail-mcp 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# ApiMail MCP (`apimail-mcp`)
+
+Stdio MCP server that proxies ApiMail HTTP API. No business logic duplication: pricing and purchases stay on the API.
+
+## End users (any machine, no local repo path)
+
+Add to Cursor / Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "apimail": {
+      "command": "npx",
+      "args": ["-y", "apimail-mcp@latest"],
+      "env": {
+        "APIMAIL_TOKEN": "YOUR_API_TOKEN",
+        "APIMAIL_BASE_URL": "https://api.apimail.me"
+      }
+    }
+  }
+}
+```
+
+Same pattern as other MCP servers: `npx` downloads and runs the package; **no filesystem path** in the config.
+
+## Publish (maintainers only)
+
+From this directory:
+
+```bash
+npm login
+npm publish
+```
+
+Bump `version` in `package.json` for each release (`npm version patch`).
+
+## Environment variables
+
+- `APIMAIL_TOKEN` — required for authenticated tools.
+- `APIMAIL_BASE_URL` — default `https://api.apimail.me`.
+- `APIMAIL_TIMEOUT_MS` — HTTP timeout ms, default `20000`.
+
+## Tools
+
+- `apimail_user_balance`
+- `apimail_domain_availability`
+- `apimail_purchase_accounts`
+- `apimail_purchased_emails`
+
+## Security
+
+Do not commit real API tokens. Use env in the MCP client only.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "apimail-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ApiMail API (stdio, Model Context Protocol)",
+  "type": "module",
+  "main": "server.js",
+  "files": [
+    "server.js"
+  ],
+  "bin": {
+    "apimail-mcp": "./server.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "prepublishOnly": "node --check server.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "apimail",
+    "stdio"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apimail/mcp"
+  }
+}

package/server.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const API_BASE_URL = (process.env.APIMAIL_BASE_URL || "https://api.apimail.me").replace(/\/+$/, "");
+const APIMAIL_TOKEN = process.env.APIMAIL_TOKEN || "";
+const REQUEST_TIMEOUT_MS = Number(process.env.APIMAIL_TIMEOUT_MS || 20000);
+
+const TOOL_DEFS = [
+  {
+    name: "apimail_user_balance",
+    description: "Get current user balance from ApiMail.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Optional API token override." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "apimail_domain_availability",
+    description: "Get public domain availability with optional filters.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        domain: { type: "string", description: "Optional domain filter, e.g. outlook.com." },
+        age: { type: "string", enum: ["fresh", "medium", "aged", "old"], description: "Optional age filter." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "apimail_purchase_accounts",
+    description: "Purchase Outlook accounts via ApiMail getEmail endpoint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Optional API token override." },
+        count: { type: "integer", minimum: 1, maximum: 500, default: 1 },
+        domain: { type: "string", description: "Optional exact domain filter." },
+        age: { type: "string", enum: ["fresh", "medium", "aged", "old"], description: "Optional age tier." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "apimail_purchased_emails",
+    description: "Fetch purchased emails by payment_id within retention period.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Optional API token override." },
+        payment_id: { type: "integer", minimum: 1 }
+      },
+      required: ["payment_id"],
+      additionalProperties: false
+    }
+  }
+];
+
+function asText(text, isError = false) {
+  return {
+    content: [{ type: "text", text }],
+    isError
+  };
+}
+
+function getTokenFromArgs(args) {
+  const local = args && typeof args.token === "string" ? args.token.trim() : "";
+  const token = local || APIMAIL_TOKEN;
+  if (!token) {
+    throw new Error("ApiMail token is required. Set APIMAIL_TOKEN env or pass token argument.");
+  }
+  return token;
+}
+
+function toQuery(params) {
+  const query = new URLSearchParams();
+  for (const [key, val] of Object.entries(params)) {
+    if (val === null || val === undefined || val === "") continue;
+    query.set(key, String(val));
+  }
+  return query.toString();
+}
+
+async function callApi(endpoint, params) {
+  const query = toQuery(params);
+  const url = `${API_BASE_URL}/${endpoint}${query ? `?${query}` : ""}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    const text = await response.text();
+
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = { status: "ERROR", value: "INVALID_JSON_RESPONSE", raw: text };
+    }
+
+    return {
+      ok: response.ok,
+      statusCode: response.status,
+      url,
+      data: parsed
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function handleTool(name, args) {
+  if (name === "apimail_user_balance") {
+    const token = getTokenFromArgs(args || {});
+    const result = await callApi("userBalance", { token });
+    return asText(JSON.stringify(result, null, 2));
+  }
+
+  if (name === "apimail_domain_availability") {
+    const params = {};
+    if (args && typeof args.domain === "string") params.domain = args.domain.trim();
+    if (args && typeof args.age === "string") params.age = args.age.trim();
+    const result = await callApi("domainAvailability", params);
+    return asText(JSON.stringify(result, null, 2));
+  }
+
+  if (name === "apimail_purchase_accounts") {
+    const token = getTokenFromArgs(args || {});
+    const count = Number(args && args.count ? args.count : 1);
+    if (!Number.isInteger(count) || count < 1 || count > 500) {
+      throw new Error("count must be an integer from 1 to 500.");
+    }
+
+    const params = { token, count };
+    if (args && typeof args.domain === "string" && args.domain.trim()) {
+      params.domain = args.domain.trim().toLowerCase();
+    }
+    if (args && typeof args.age === "string" && args.age.trim()) {
+      params.age = args.age.trim().toLowerCase();
+    }
+
+    const result = await callApi("getEmail", params);
+    return asText(JSON.stringify(result, null, 2));
+  }
+
+  if (name === "apimail_purchased_emails") {
+    const token = getTokenFromArgs(args || {});
+    const paymentId = Number(args && args.payment_id);
+    if (!Number.isInteger(paymentId) || paymentId <= 0) {
+      throw new Error("payment_id must be a positive integer.");
+    }
+    const result = await callApi("purchasedEmails", { token, payment_id: paymentId });
+    return asText(JSON.stringify(result, null, 2));
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+const server = new Server(
+  { name: "apimail-mcp", version: "1.1.0" },
+  { capabilities: { tools: { listChanged: false } } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const name = request.params?.name;
+  const args = request.params?.arguments || {};
+  try {
+    return await handleTool(name, args);
+  } catch (error) {
+    return asText(String(error?.message || error), true);
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);