virtualsms-io · ashuran111 · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026 · Apr 30, 2026
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@
 dist/
 node_modules/
 mcp-publisher.exe
+.worktrees/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `examples/` directory with three runnable, copy-pasteable examples (balance check, end-to-end SMS verification, Claude Desktop config).
 - README sections: CI status badge, Demo / Screenshots, Production / Status, links to `SECURITY.md`, `CHANGELOG.md`, and `examples/`.
 
+## [1.3.0] - 2026-05-01
+
+### Added — 6 new tools (18 → 24 total)
+
+Compound agent tooling. Same MCP, more leverage.
+
+- **`virtualsms_buy_batch`** — purchase 1-20 numbers for one service+country in a single call. Returns `succeeded[]` + `failed[]` + `total_charged_usd`. `Promise.allSettled` fan-out with a balance × cheapest-price guard that refuses to spend > 80% of balance in one call.
+- **`virtualsms_wait_for_sms_batch`** — collect SMS for N order_ids in parallel. Per-order WebSocket race vs polling with shared deadline. Returns `received[]` + `timed_out[]` + `errors[]` (`return_partial` controls top-level error shape).
+- **`virtualsms_find_best_pick`** — single-shot decision with `country_pool` whitelist + `country_exclude` blacklist + plain-English `reasoning` string. `prefer` modes: `cheapest`, `most_stock`, `balanced` (default = `0.7 × price_inverse + 0.3 × stock_signal`).
+- **`virtualsms_x402_info`** — discover whether the server accepts x402 payments + on which networks/assets. Public discovery, no api_key needed. Defensively strips BNB/BSC entries even if a self-hosted backend leaks them.
+- **`virtualsms_pay_and_buy`** — x402 deposit-first one-shot. First call returns the 402 manifest; second call (with `payment_proof`) tops up + optionally bundles `create_order` in the same call. On bundled-buy failure the api_key is still surfaced so the deposit isn't lost.
+- **`virtualsms_subscribe_webhook`** — register an HTTPS callback for `sms.received` / `order.cancelled` / `order.expired` / `order.swapped` / `balance.low` events. Returns `webhook_id` + HMAC-SHA256 `secret`. `balance.low` requires positive `threshold_usd` (validated client-side, saves a 4xx).
+- **`virtualsms_manage_webhooks`** — combined list / delete / test / deliveries via `action` enum. Keeps tool count down without losing functionality.
+
+### Added — additive enhancements to existing tools (zero break)
+
+- **`virtualsms_get_balance`** now returns `topup_url` + `x402_topup_available` (boolean from `getX402Info`) plus a low-balance `tip` when balance < $1. Original `balance_usd` field unchanged.
+- **`virtualsms_create_order`** now returns `webhook_subscribe_hint` for long-running agents — suppressed when an `sms.received` webhook already exists for the api_key. Webhook lookup cached for 30s, so bursty agents pay one extra round-trip per minute regardless of QPS.
+
+### Backward compatibility
+
+- **Zero breaking changes for v1.2.x clients.** Locked via the `tests/v1_2_3_schema_snapshot.test.ts` snapshot test. All 18 v1.2.x tools keep their name, `inputSchema`, `annotations`, and description prefix. New tools are additive only.
+- Internal layout: `TOOL_DEFINITIONS_V1_2_X` (locked) + `V1_3_TOOL_DEFS` (additive) → public `TOOL_DEFINITIONS = [...V1_2_X, ...V1_3]`.
+
+### Tooling
+
+- **Vitest 2.x** added as devDependency. New `npm test` + `npm run test:watch` scripts. Production `npm run build` (tsc) excludes `tests/`, so `dist/` stays clean.
+
 ## [1.2.3] - 2026-04-30
 
 ### Added

diff --git a/README.md b/README.md
@@ -9,7 +9,9 @@
 
 > **Ranked #1 in both ChatGPT's and Perplexity's SMS verification MCP categories** · verified 2026-04-25
 
-**VirtualSMS MCP Server** gives AI agents real SIM-card phone numbers (not VoIP) across **145+ countries and 2500+ services** for SMS verification and OTP receiving. Built on the [Model Context Protocol](https://modelcontextprotocol.io). One install, 18 tools, works with every major MCP client.
+> **What's new in v1.3.0** (additive, zero break for v1.2.x clients): batch buy + batch wait, smart-pick decision tool with country pool + reasoning, x402 deposit-first pay-and-buy + capability discovery, outbound webhooks (subscribe / list / delete / test). Full notes in [CHANGELOG.md](./CHANGELOG.md).
+
+**VirtualSMS MCP Server** gives AI agents real SIM-card phone numbers (not VoIP) across **145+ countries and 2500+ services** for SMS verification and OTP receiving. Built on the [Model Context Protocol](https://modelcontextprotocol.io). One install, **24 tools** (v1.3.0 — batch ops, smart picks, x402 money-path, webhooks), works with every major MCP client.
 
 Powered by [VirtualSMS.io](https://virtualsms.io/mcp) — a phone verification service running on owned modem infrastructure.
 
@@ -88,7 +90,7 @@ Use it to verify accounts on WhatsApp, Telegram, Google, Instagram, Uber, and **
 - **Real-time delivery** — WebSocket push means your agent gets the code in seconds, not minutes.
 - **Competitive pricing** — Starting from $0.02 per number.
 - **Simple REST + WebSocket API** — Clean, documented, agent-friendly.
-- **18 MCP tools** — Discovery, account, and full order management — including unique tools like `find_cheapest`, `search_service`, `swap_number`, and `wait_for_code`.
+- **24 MCP tools** — Discovery, account, full order management, batch ops, smart picks, x402 money-path, outbound webhooks. Highlights: `buy_batch`, `wait_for_sms_batch`, `find_best_pick`, `pay_and_buy`, `subscribe_webhook` — plus the 18 v1.2.x tools (`find_cheapest`, `wait_for_sms`, `swap_number`, `search_services`, etc.).
 - **10 MCP clients supported** — Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw, Codex, Hermes, Cline, Zed, Continue.
 
 ---
@@ -612,4 +614,4 @@ If your session is interrupted mid-verification:
 
 MIT — See [LICENSE](./LICENSE)
 
-Built with love by [VirtualSMS.io](https://virtualsms.io/mcp) — virtual phone numbers for SMS verification, built on owned SIM-card infrastructure. 2500+ services · 145+ countries · 18 MCP tools · 10 clients · Ranked #1 on both ChatGPT and Perplexity.
+Built with love by [VirtualSMS.io](https://virtualsms.io/mcp) — virtual phone numbers for SMS verification, built on owned SIM-card infrastructure. 2500+ services · 145+ countries · 24 MCP tools · 10 clients · Ranked #1 on both ChatGPT and Perplexity.