@voidmob/mcp 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# VoidMob MCP
+
+Mobile proxies, non-VoIP SMS verifications, and global eSIMs for AI agents and MCP clients.
+
+```bash
+npx -y @voidmob/mcp
+```
+
+## Quick Start
+
+Add VoidMob to your MCP client. No auth, no config, no API key.
+
+### Claude Code
+
+```bash
+claude mcp add voidmob -- npx -y @voidmob/mcp
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "voidmob": {
+      "command": "npx",
+      "args": ["-y", "@voidmob/mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your config file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "voidmob": {
+      "command": "npx",
+      "args": ["-y", "@voidmob/mcp"]
+    }
+  }
+}
+```
+
+Restart your client. You now have 18 tools for mobile proxies, SMS verification, eSIM, and wallet operations.
+
+## Available Tools
+
+### Mobile Proxies
+
+| Tool | Description |
+|------|-------------|
+| `search_proxies` | Search mobile proxy options by country or type |
+| `get_proxy_pricing` | Get detailed pricing for a proxy type + country |
+| `purchase_proxy` | Purchase a mobile proxy (pay-per-GB or dedicated monthly) |
+| `get_proxy_status` | Check bandwidth usage and connection details |
+| `rotate_proxy` | Rotate to a new IP address |
+
+### SMS (US non-VoIP)
+
+| Tool | Description |
+|------|-------------|
+| `search_sms_services` | Search US non-VoIP SMS verification services by name or category |
+| `get_sms_price` | Get pricing for a US non-VoIP SMS verification service |
+| `rent_number` | Rent a US non-VoIP phone number for verification (5 min expiry) |
+| `get_messages` | Check for incoming SMS messages on a rented number |
+| `cancel_rental` | Cancel a rental (full refund if no messages received) |
+
+### eSIM
+
+| Tool | Description |
+|------|-------------|
+| `search_esim_plans` | Search eSIM data plans by country, duration, or data amount |
+| `get_esim_plan_details` | Get full plan details including APN and top-up info |
+| `purchase_esim` | Purchase an eSIM plan and get a QR code for installation |
+| `get_esim_usage` | Check data usage, remaining balance, and time left |
+| `topup_esim` | Add more data to an active eSIM order |
+
+### Wallet
+
+| Tool | Description |
+|------|-------------|
+| `get_balance` | Get wallet balance and recent transactions |
+| `deposit` | Create a crypto deposit (BTC, ETH, SOL) |
+
+### General
+
+| Tool | Description |
+|------|-------------|
+| `list_orders` | List all orders across SMS, eSIM, and proxy services |
+
+## Example Conversations
+
+These are things you can ask Claude, Cursor, or any MCP client after adding VoidMob:
+
+> Set up a dedicated US mobile proxy and give me the credentials
+
+> Rotate my US dedicated proxy IP
+
+> How much does a 5GB eSIM plan in the UK cost?
+
+> Rent me a US phone number for WhatsApp verification
+
+> Check if my verification code arrived
+
+> Find the cheapest eSIM plan for 2 weeks in Japan with at least 5GB
+
+> Show me all my active orders
+
+## Sandbox Mode
+
+VoidMob MCP currently runs in **sandbox mode**. Everything works, but the data is mock.
+
+- **$50 starting balance** - enough to try every tool
+- **Stateful** - renting a number deducts balance, messages appear after a few seconds, deposits auto-confirm
+- **Deposits auto-confirm** in ~5 seconds
+- **State resets** on server restart
+- **No auth required** - zero config, just `npx -y @voidmob/mcp`
+
+The sandbox is designed to let you explore the full flow: deposit funds, rent a number, receive a verification code, check your balance. Everything behaves like the real API, just with mock data underneath.
+
+## API Access
+
+Currently in sandbox mode. Join the waitlist at [voidmob.com](https://voidmob.com) for early API access.
+
+---
+
+<p align="center">
+  <a href="https://voidmob.com">Website</a> · <a href="https://github.com/voidmobcom/voidmob-mcp">GitHub</a> · <a href="https://x.com/voidmob_com">X (Twitter)</a> · MIT License
+</p>

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerWalletTools } from "./tools/wallet.js";
+import { registerSmsTools } from "./tools/sms.js";
+import { registerEsimTools } from "./tools/esim.js";
+import { registerProxyTools } from "./tools/proxy.js";
+import { registerOrdersTools } from "./tools/orders.js";
+const server = new McpServer({
+    name: "@voidmob/mcp",
+    version: "0.1.0",
+});
+registerWalletTools(server);
+registerSmsTools(server);
+registerEsimTools(server);
+registerProxyTools(server);
+registerOrdersTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/mock-data/esim.d.ts

@@ -0,0 +1,17 @@
+export interface EsimPlan {
+    planId: string;
+    name: string;
+    country: string;
+    region: string;
+    data: number;
+    duration: number;
+    price: number;
+    carrier: string;
+    apn: string;
+    routing: string;
+    topupAvailable: boolean;
+    topupPrice: number;
+}
+export declare const esimPlans: EsimPlan[];
+export declare function searchPlans(country?: string, duration?: number, dataAmount?: number): EsimPlan[];
+export declare function getPlan(planId: string): EsimPlan | undefined;

package/dist/mock-data/esim.js

@@ -0,0 +1,30 @@
+export const esimPlans = [
+    { planId: "esim_jp_3g_7d", name: "Japan 3GB / 7 Days", country: "JP", region: "Asia", data: 3, duration: 7, price: 4.50, carrier: "IIJmio", apn: "iijmio.jp", routing: "Tokyo, Japan", topupAvailable: true, topupPrice: 1.80 },
+    { planId: "esim_jp_5g_14d", name: "Japan 5GB / 14 Days", country: "JP", region: "Asia", data: 5, duration: 14, price: 7.50, carrier: "IIJmio", apn: "iijmio.jp", routing: "Tokyo, Japan", topupAvailable: true, topupPrice: 1.80 },
+    { planId: "esim_jp_10g_30d", name: "Japan 10GB / 30 Days", country: "JP", region: "Asia", data: 10, duration: 30, price: 12.00, carrier: "IIJmio", apn: "iijmio.jp", routing: "Tokyo, Japan", topupAvailable: true, topupPrice: 1.50 },
+    { planId: "esim_jp_unl_30d", name: "Japan Unlimited / 30 Days", country: "JP", region: "Asia", data: 999, duration: 30, price: 22.00, carrier: "SoftBank", apn: "plus.4g", routing: "Tokyo, Japan", topupAvailable: false, topupPrice: 0 },
+    { planId: "esim_us_5g_7d", name: "USA 5GB / 7 Days", country: "US", region: "North America", data: 5, duration: 7, price: 6.00, carrier: "T-Mobile", apn: "fast.t-mobile.com", routing: "Los Angeles, US", topupAvailable: true, topupPrice: 1.50 },
+    { planId: "esim_us_10g_30d", name: "USA 10GB / 30 Days", country: "US", region: "North America", data: 10, duration: 30, price: 11.00, carrier: "T-Mobile", apn: "fast.t-mobile.com", routing: "Los Angeles, US", topupAvailable: true, topupPrice: 1.30 },
+    { planId: "esim_us_20g_30d", name: "USA 20GB / 30 Days", country: "US", region: "North America", data: 20, duration: 30, price: 18.00, carrier: "T-Mobile", apn: "fast.t-mobile.com", routing: "Los Angeles, US", topupAvailable: true, topupPrice: 1.10 },
+    { planId: "esim_gb_5g_7d", name: "UK 5GB / 7 Days", country: "GB", region: "Europe", data: 5, duration: 7, price: 5.50, carrier: "Three", apn: "three.co.uk", routing: "London, UK", topupAvailable: true, topupPrice: 1.40 },
+    { planId: "esim_gb_10g_30d", name: "UK 10GB / 30 Days", country: "GB", region: "Europe", data: 10, duration: 30, price: 10.00, carrier: "Three", apn: "three.co.uk", routing: "London, UK", topupAvailable: true, topupPrice: 1.20 },
+    { planId: "esim_de_5g_7d", name: "Germany 5GB / 7 Days", country: "DE", region: "Europe", data: 5, duration: 7, price: 5.00, carrier: "O2", apn: "internet", routing: "Frankfurt, DE", topupAvailable: true, topupPrice: 1.30 },
+    { planId: "esim_de_10g_30d", name: "Germany 10GB / 30 Days", country: "DE", region: "Europe", data: 10, duration: 30, price: 9.00, carrier: "O2", apn: "internet", routing: "Frankfurt, DE", topupAvailable: true, topupPrice: 1.10 },
+    { planId: "esim_th_5g_7d", name: "Thailand 5GB / 7 Days", country: "TH", region: "Asia", data: 5, duration: 7, price: 3.50, carrier: "AIS", apn: "internet", routing: "Bangkok, TH", topupAvailable: true, topupPrice: 0.90 },
+    { planId: "esim_th_15g_30d", name: "Thailand 15GB / 30 Days", country: "TH", region: "Asia", data: 15, duration: 30, price: 8.00, carrier: "AIS", apn: "internet", routing: "Bangkok, TH", topupAvailable: true, topupPrice: 0.70 },
+    { planId: "esim_tr_5g_7d", name: "Turkey 5GB / 7 Days", country: "TR", region: "Europe", data: 5, duration: 7, price: 4.00, carrier: "Turkcell", apn: "internet", routing: "Istanbul, TR", topupAvailable: true, topupPrice: 1.00 },
+    { planId: "esim_br_5g_7d", name: "Brazil 5GB / 7 Days", country: "BR", region: "South America", data: 5, duration: 7, price: 5.50, carrier: "Claro", apn: "claro.com.br", routing: "Sao Paulo, BR", topupAvailable: true, topupPrice: 1.30 },
+];
+export function searchPlans(country, duration, dataAmount) {
+    let results = esimPlans;
+    if (country)
+        results = results.filter((p) => p.country === country);
+    if (duration)
+        results = results.filter((p) => p.duration >= duration);
+    if (dataAmount)
+        results = results.filter((p) => p.data >= dataAmount);
+    return results.sort((a, b) => a.price - b.price);
+}
+export function getPlan(planId) {
+    return esimPlans.find((p) => p.planId === planId);
+}

package/dist/mock-data/proxy.d.ts

@@ -0,0 +1,17 @@
+export type ProxyOption = {
+    country: string;
+    carrier: string;
+    type: "gb";
+    pricePerGb: number;
+    network: string;
+} | {
+    country: string;
+    carrier: string;
+    type: "dedicated";
+    pricePerMonth: number;
+    bandwidth: number;
+    network: string;
+};
+export declare const proxyOptions: ProxyOption[];
+export declare function searchProxyOptions(country?: string, type?: string): ProxyOption[];
+export declare function getProxyPricing(type: string, country: string): ProxyOption[];

package/dist/mock-data/proxy.js

@@ -0,0 +1,29 @@
+export const proxyOptions = [
+    { country: "US", carrier: "Verizon", type: "gb", pricePerGb: 2.99, network: "5G" },
+    { country: "US", carrier: "T-Mobile", type: "gb", pricePerGb: 2.49, network: "5G" },
+    { country: "US", carrier: "AT&T", type: "gb", pricePerGb: 2.79, network: "5G" },
+    { country: "US", carrier: "Verizon", type: "dedicated", pricePerMonth: 80, bandwidth: 30, network: "5G" },
+    { country: "US", carrier: "T-Mobile", type: "dedicated", pricePerMonth: 70, bandwidth: 30, network: "5G" },
+    { country: "GB", carrier: "Vodafone", type: "gb", pricePerGb: 2.99, network: "5G" },
+    { country: "GB", carrier: "EE", type: "gb", pricePerGb: 2.79, network: "5G" },
+    { country: "GB", carrier: "Vodafone", type: "dedicated", pricePerMonth: 85, bandwidth: 30, network: "5G" },
+    { country: "DE", carrier: "Telekom", type: "gb", pricePerGb: 3.29, network: "5G" },
+    { country: "DE", carrier: "Telekom", type: "dedicated", pricePerMonth: 90, bandwidth: 25, network: "5G" },
+    { country: "NL", carrier: "KPN", type: "gb", pricePerGb: 2.79, network: "4G LTE" },
+    { country: "NL", carrier: "KPN", type: "dedicated", pricePerMonth: 75, bandwidth: 25, network: "4G LTE" },
+    { country: "BR", carrier: "Claro", type: "gb", pricePerGb: 1.99, network: "4G LTE" },
+    { country: "IN", carrier: "Jio", type: "gb", pricePerGb: 0.99, network: "5G" },
+    { country: "JP", carrier: "NTT Docomo", type: "gb", pricePerGb: 3.49, network: "5G" },
+    { country: "JP", carrier: "NTT Docomo", type: "dedicated", pricePerMonth: 100, bandwidth: 25, network: "5G" },
+];
+export function searchProxyOptions(country, type) {
+    let results = proxyOptions;
+    if (country)
+        results = results.filter((p) => p.country === country);
+    if (type)
+        results = results.filter((p) => p.type === type);
+    return results;
+}
+export function getProxyPricing(type, country) {
+    return proxyOptions.filter((p) => p.type === type && p.country === country);
+}

package/dist/mock-data/sms.d.ts

@@ -0,0 +1,13 @@
+export interface SmsService {
+    id: string;
+    name: string;
+    category: string;
+    price: number;
+    estimatedDelivery: string;
+}
+export declare const smsServices: SmsService[];
+export declare function searchServices(query?: string): SmsService[];
+export declare function getServicePrice(serviceId: string): {
+    service: SmsService;
+    price: number;
+} | null;

package/dist/mock-data/sms.js

@@ -0,0 +1,24 @@
+export const smsServices = [
+    { id: "whatsapp", name: "WhatsApp", category: "messaging", price: 2.50, estimatedDelivery: "1-3 minutes" },
+    { id: "telegram", name: "Telegram", category: "messaging", price: 1.50, estimatedDelivery: "1-2 minutes" },
+    { id: "google", name: "Google / Gmail", category: "email", price: 1.80, estimatedDelivery: "1-3 minutes" },
+    { id: "twitter", name: "Twitter / X", category: "social", price: 2.00, estimatedDelivery: "1-5 minutes" },
+    { id: "instagram", name: "Instagram", category: "social", price: 2.20, estimatedDelivery: "1-3 minutes" },
+    { id: "discord", name: "Discord", category: "messaging", price: 1.20, estimatedDelivery: "1-2 minutes" },
+    { id: "tiktok", name: "TikTok", category: "social", price: 2.50, estimatedDelivery: "1-5 minutes" },
+    { id: "facebook", name: "Facebook", category: "social", price: 1.80, estimatedDelivery: "1-3 minutes" },
+    { id: "uber", name: "Uber", category: "ride-hailing", price: 2.00, estimatedDelivery: "1-3 minutes" },
+    { id: "openai", name: "OpenAI / ChatGPT", category: "ai", price: 3.00, estimatedDelivery: "1-3 minutes" },
+];
+export function searchServices(query) {
+    if (!query)
+        return smsServices;
+    const q = query.toLowerCase();
+    return smsServices.filter((s) => s.name.toLowerCase().includes(q) || s.category.toLowerCase().includes(q) || s.id.toLowerCase().includes(q));
+}
+export function getServicePrice(serviceId) {
+    const service = smsServices.find((s) => s.id === serviceId);
+    if (!service)
+        return null;
+    return { service, price: service.price };
+}

package/dist/sandbox/state.d.ts

@@ -0,0 +1,75 @@
+export interface SmsMessage {
+    from: string;
+    text: string;
+    receivedAt: number;
+}
+export interface SmsRental {
+    rentalId: string;
+    number: string;
+    service: string;
+    country: string;
+    status: "active" | "completed" | "cancelled" | "expired";
+    messages: SmsMessage[];
+    expiry: number;
+    createdAt: number;
+    price: number;
+}
+export interface EsimOrder {
+    orderId: string;
+    planId: string;
+    planName: string;
+    country: string;
+    dataTotal: number;
+    dataUsed: number;
+    status: "active" | "completed" | "expired";
+    qrUrl: string;
+    apn: string;
+    expiry: number;
+    createdAt: number;
+    price: number;
+}
+export interface ProxyEntry {
+    proxyId: string;
+    type: "gb" | "dedicated";
+    country: string;
+    carrier: string;
+    credentials: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+    };
+    bandwidthUsed: number;
+    bandwidthTotal: number;
+    status: "active" | "expired";
+    ip: string;
+    createdAt: number;
+    price: number;
+}
+export interface Deposit {
+    invoiceId: string;
+    amount: number;
+    currency: string;
+    status: "pending" | "completed";
+    createdAt: number;
+}
+export interface Transaction {
+    id: string;
+    type: "deposit" | "sms_rental" | "esim_purchase" | "proxy_purchase" | "refund" | "topup";
+    amount: number;
+    description: string;
+    createdAt: number;
+}
+declare class SandboxState {
+    balance: number;
+    transactions: Transaction[];
+    smsRentals: Map<string, SmsRental>;
+    esimOrders: Map<string, EsimOrder>;
+    proxies: Map<string, ProxyEntry>;
+    deposits: Map<string, Deposit>;
+    deductBalance(amount: number, type: Transaction["type"], description: string): boolean;
+    addBalance(amount: number, type: Transaction["type"], description: string): void;
+    resolvePendingDeposits(): void;
+}
+export declare const state: SandboxState;
+export {};

package/dist/sandbox/state.js

@@ -0,0 +1,42 @@
+import { generateId } from "../utils/validation.js";
+class SandboxState {
+    balance = 50.0;
+    transactions = [];
+    smsRentals = new Map();
+    esimOrders = new Map();
+    proxies = new Map();
+    deposits = new Map();
+    deductBalance(amount, type, description) {
+        if (this.balance < amount)
+            return false;
+        this.balance = Math.round((this.balance - amount) * 100) / 100;
+        this.transactions.push({
+            id: generateId("tx"),
+            type,
+            amount: -amount,
+            description,
+            createdAt: Date.now(),
+        });
+        return true;
+    }
+    addBalance(amount, type, description) {
+        this.balance = Math.round((this.balance + amount) * 100) / 100;
+        this.transactions.push({
+            id: generateId("tx"),
+            type,
+            amount,
+            description,
+            createdAt: Date.now(),
+        });
+    }
+    resolvePendingDeposits() {
+        const now = Date.now();
+        for (const deposit of this.deposits.values()) {
+            if (deposit.status === "pending" && now - deposit.createdAt > 5000) {
+                deposit.status = "completed";
+                this.addBalance(deposit.amount, "deposit", `Crypto deposit (${deposit.currency})`);
+            }
+        }
+    }
+}
+export const state = new SandboxState();

package/dist/tools/esim.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEsimTools(server: McpServer): void;

package/dist/tools/esim.js

@@ -0,0 +1,218 @@
+import { z } from "zod";
+import { state } from "../sandbox/state.js";
+import { validateCountry, ToolError, generateId } from "../utils/validation.js";
+import { formatUsd, formatGb, formatTimeRemaining } from "../utils/format.js";
+import { searchPlans, getPlan } from "../mock-data/esim.js";
+function errorResponse(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+function formatData(gb) {
+    return gb >= 999 ? "Unlimited" : formatGb(gb);
+}
+export function registerEsimTools(server) {
+    server.tool("search_esim_plans", "Search available eSIM data plans. Filter by country, minimum duration, or minimum data amount.", {
+        country: z.string().describe("ISO 3166-1 alpha-2 country code (e.g., JP, US, GB)"),
+        duration: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("Minimum plan duration in days"),
+        dataAmount: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("Minimum data amount in GB"),
+    }, async ({ country, duration, dataAmount }) => {
+        try {
+            const validatedCountry = validateCountry(country);
+            const results = searchPlans(validatedCountry, duration, dataAmount);
+            if (results.length === 0) {
+                return errorResponse("No eSIM plans found matching your criteria. Try a different country or adjust filters.");
+            }
+            let text = `Found ${results.length} eSIM plan(s) for ${validatedCountry}:\n\n`;
+            for (const plan of results) {
+                text += `  ${plan.name} (${plan.planId})\n`;
+                text += `    Data:     ${formatData(plan.data)}\n`;
+                text += `    Duration: ${plan.duration} days\n`;
+                text += `    Price:    ${formatUsd(plan.price)}\n`;
+                text += `    Carrier:  ${plan.carrier}\n`;
+                text += `    Routing:  ${plan.routing}\n`;
+                text += `    Top-up:   ${plan.topupAvailable ? `Yes (${formatUsd(plan.topupPrice)}/GB)` : "No"}\n\n`;
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return errorResponse(e.message);
+            throw e;
+        }
+    });
+    server.tool("get_esim_plan_details", "Get full details for a specific eSIM plan including APN settings and top-up availability.", {
+        planId: z.string().describe("Plan ID (e.g., 'esim_jp_3g_7d')"),
+    }, async ({ planId }) => {
+        try {
+            const plan = getPlan(planId);
+            if (!plan) {
+                return errorResponse(`Plan not found: ${planId}. Use search_esim_plans to browse available plans.`);
+            }
+            const text = [
+                `${plan.name}`,
+                ``,
+                `  Plan ID:   ${plan.planId}`,
+                `  Country:   ${plan.country}`,
+                `  Region:    ${plan.region}`,
+                `  Data:      ${formatData(plan.data)}`,
+                `  Duration:  ${plan.duration} days`,
+                `  Price:     ${formatUsd(plan.price)}`,
+                `  Carrier:   ${plan.carrier}`,
+                `  APN:       ${plan.apn}`,
+                `  Routing:   ${plan.routing}`,
+                `  Top-up:    ${plan.topupAvailable ? `Available at ${formatUsd(plan.topupPrice)}/GB` : "Not available"}`,
+            ].join("\n");
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return errorResponse(e.message);
+            throw e;
+        }
+    });
+    server.tool("purchase_esim", "Purchase an eSIM plan. Deducts cost from wallet and provides QR code for installation.", {
+        planId: z.string().describe("Plan ID to purchase (e.g., 'esim_jp_3g_7d')"),
+    }, async ({ planId }) => {
+        try {
+            const plan = getPlan(planId);
+            if (!plan) {
+                return errorResponse(`Plan not found: ${planId}. Use search_esim_plans to browse available plans.`);
+            }
+            if (!state.deductBalance(plan.price, "esim_purchase", `eSIM: ${plan.name}`)) {
+                return errorResponse(`Insufficient balance. Need ${formatUsd(plan.price)} but have ${formatUsd(state.balance)}. Use deposit to add funds.`);
+            }
+            const orderId = generateId("ord");
+            const now = Date.now();
+            state.esimOrders.set(orderId, {
+                orderId,
+                planId: plan.planId,
+                planName: plan.name,
+                country: plan.country,
+                dataTotal: plan.data,
+                dataUsed: 0,
+                status: "active",
+                qrUrl: `https://sandbox.voidmob.com/esim/qr/${orderId}`,
+                apn: plan.apn,
+                expiry: now + plan.duration * 24 * 60 * 60 * 1000,
+                createdAt: now,
+                price: plan.price,
+            });
+            const text = [
+                `eSIM purchased!`,
+                ``,
+                `  Order ID:  ${orderId}`,
+                `  Plan:      ${plan.name}`,
+                `  Data:      ${formatData(plan.data)}`,
+                `  Duration:  ${plan.duration} days`,
+                `  Cost:      ${formatUsd(plan.price)}`,
+                `  Carrier:   ${plan.carrier}`,
+                `  Routing:   ${plan.routing}`,
+                ``,
+                `  QR Code:   https://sandbox.voidmob.com/esim/qr/${orderId}`,
+                `  APN:       ${plan.apn}`,
+                ``,
+                `Setup steps:`,
+                `  1. Scan the QR code with your device camera`,
+                `  2. Set APN to "${plan.apn}"`,
+                `  3. Enable the eSIM line in Settings`,
+                ``,
+                `Use get_esim_usage with the order ID to check data consumption.`,
+            ].join("\n");
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return errorResponse(e.message);
+            throw e;
+        }
+    });
+    server.tool("get_esim_usage", "Check data usage and status for an eSIM order. Shows data consumed, remaining, and time left.", {
+        orderId: z.string().describe("Order ID returned from purchase_esim"),
+    }, async ({ orderId }) => {
+        try {
+            const order = state.esimOrders.get(orderId);
+            if (!order) {
+                return errorResponse(`Order not found: ${orderId}`);
+            }
+            const now = Date.now();
+            if (order.status === "active" && now >= order.expiry) {
+                order.status = "expired";
+            }
+            // Simulate usage growth: ~0.1 GB/hour, capped at 95% of total
+            const hoursElapsed = (now - order.createdAt) / 3600000;
+            const simulatedUsage = hoursElapsed * 0.1;
+            const maxUsage = order.dataTotal * 0.95;
+            order.dataUsed = Math.round(Math.min(simulatedUsage, maxUsage) * 100) / 100;
+            const daysLeft = Math.max(0, Math.ceil((order.expiry - now) / 86400000));
+            const isUnlimited = order.dataTotal >= 999;
+            const dataRemaining = isUnlimited
+                ? "Unlimited"
+                : formatGb(Math.max(0, order.dataTotal - order.dataUsed));
+            const text = [
+                `eSIM Usage — ${order.planName}`,
+                ``,
+                `  Order ID:       ${order.orderId}`,
+                `  Status:         ${order.status}`,
+                `  Data used:      ${formatGb(order.dataUsed)}`,
+                `  Data remaining: ${dataRemaining}`,
+                `  Data total:     ${formatData(order.dataTotal)}`,
+                `  Days left:      ${order.status === "expired" ? "Expired" : `${daysLeft} day(s)`}`,
+                `  Expires:        ${order.status === "expired" ? "Expired" : formatTimeRemaining(order.expiry)}`,
+            ].join("\n");
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return errorResponse(e.message);
+            throw e;
+        }
+    });
+    server.tool("topup_esim", "Add more data to an active eSIM order. Only available for plans that support top-ups.", {
+        orderId: z.string().describe("Order ID to top up"),
+        dataAmount: z.number().positive().describe("Amount of data to add in GB"),
+    }, async ({ orderId, dataAmount }) => {
+        try {
+            const order = state.esimOrders.get(orderId);
+            if (!order) {
+                return errorResponse(`Order not found: ${orderId}`);
+            }
+            if (order.status !== "active") {
+                return errorResponse(`Order ${orderId} is ${order.status}. Only active orders can be topped up.`);
+            }
+            const plan = getPlan(order.planId);
+            if (!plan || !plan.topupAvailable) {
+                return errorResponse(`Top-up is not available for this plan (${order.planName}).`);
+            }
+            const cost = Math.round(dataAmount * plan.topupPrice * 100) / 100;
+            if (!state.deductBalance(cost, "topup", `eSIM top-up: +${formatGb(dataAmount)} for ${order.planName}`)) {
+                return errorResponse(`Insufficient balance. Need ${formatUsd(cost)} but have ${formatUsd(state.balance)}. Use deposit to add funds.`);
+            }
+            order.dataTotal = Math.round((order.dataTotal + dataAmount) * 100) / 100;
+            const text = [
+                `Top-up successful!`,
+                ``,
+                `  Order:     ${order.orderId}`,
+                `  Added:     ${formatGb(dataAmount)}`,
+                `  Cost:      ${formatUsd(cost)}`,
+                `  New total: ${formatData(order.dataTotal)}`,
+                `  Balance:   ${formatUsd(state.balance)}`,
+            ].join("\n");
+            return { content: [{ type: "text", text }] };
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return errorResponse(e.message);
+            throw e;
+        }
+    });
+}

package/dist/tools/orders.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerOrdersTools(server: McpServer): void;