virtualsms-mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,12 @@
-# VirtualSMS MCP Server
+# VirtualSMS MCP Server — SMS Verification for AI Agents
 
-Receive SMS verification codes directly inside your AI agent workflows. Supports Claude Desktop, Cursor, and any MCP-compatible client.
+[![npm version](https://img.shields.io/npm/v/virtualsms-mcp.svg)](https://www.npmjs.com/package/virtualsms-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/virtualsms-io/mcp-server?style=social)](https://github.com/virtualsms-io/mcp-server)
 
-**Powered by [VirtualSMS.io](https://virtualsms.io)** — virtual phone numbers for SMS verification.
+**VirtualSMS MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents access to a complete SMS verification API. Get a virtual phone number, receive SMS online, and extract verification codes — all without leaving your AI workflow.
+
+Powered by [VirtualSMS.io](https://virtualsms.io) — a phone verification service running on own infrastructure across 200+ countries.
 
 ---
 
@@ -22,6 +26,35 @@ Get your API key at [virtualsms.io](https://virtualsms.io).
 
 ---
 
+## What is VirtualSMS?
+
+[VirtualSMS.io](https://virtualsms.io) is a **temporary phone number API** for SMS verification. Unlike resellers that aggregate other providers, VirtualSMS operates its own modem infrastructure — giving you direct access to real SIM cards across 200+ countries.
+
+Use it to verify accounts on WhatsApp, Telegram, Google, Instagram, and 500+ other services — programmatically, via API or MCP.
+
+---
+
+## Why VirtualSMS?
+
+- **Own infrastructure** — Not a reseller. Real SIM cards on our own hardware.
+- **200+ countries** — Find the cheapest number for any service worldwide.
+- **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.
+- **11 MCP tools** — Everything from price discovery to one-step code retrieval.
+
+---
+
+## Migrating from SMS-Activate or DaisySMS?
+
+If you're moving away from **SMS-Activate** or **DaisySMS** (closing March 2025), VirtualSMS is a straightforward alternative with comparable service coverage, competitive pricing, and a modern API built for programmatic use.
+
+Just swap your API key and update the base URL — the concepts (buy number → wait for SMS → get code) are identical.
+
+👉 [Sign up at VirtualSMS.io](https://virtualsms.io) and get started in minutes.
+
+---
+
 ## Configuration
 
 ### Claude Desktop
@@ -82,7 +115,7 @@ list_services()
 ```
 
 #### `list_countries`
-Get all available countries for SMS verification.
+Get all available countries for phone verification.
 
 ```
 list_countries()
@@ -137,7 +170,7 @@ Optional `status` filter: `"pending"`, `"sms_received"`, `"cancelled"`, `"comple
 ### Order Management Tools (API key required)
 
 #### `buy_number`
-Purchase a virtual phone number.
+Purchase a virtual phone number for a specific service and country.
 
 ```
 buy_number(service: "telegram", country: "US")
@@ -145,7 +178,7 @@ buy_number(service: "telegram", country: "US")
 ```
 
 #### `check_sms`
-Check if an SMS code has arrived for an order.
+Check if an SMS verification code has arrived.
 
 ```
 check_sms(order_id: "abc123")
@@ -184,28 +217,35 @@ On timeout, returns `order_id` for recovery:
 
 ---
 
+
+## Number Rentals (Coming Soon)
+
+Need to keep the same phone number for days or weeks? VirtualSMS supports **number rentals** for recurring verifications — perfect for long-running automations, dev testing, and accounts that require re-verification with the same number.
+
+Rental tools (`rent_number`, `extend_rental`, `list_rentals`) are coming in v1.1. See the [Roadmap](./ROADMAP.md).
+
 ## How It Works
 
 ### WebSocket vs Polling
 
 `wait_for_code` uses a two-tier delivery system:
 
-1. **WebSocket (instant)** — connects to `wss://virtualsms.io/ws/orders?order_id=xxx` immediately after buying the number. When the SMS arrives, the server pushes it in real-time. Typical delivery: 2-15 seconds.
+1. **WebSocket (instant)** — connects to `wss://virtualsms.io/ws/orders?order_id=xxx` immediately after purchase. When the SMS arrives, the server pushes it in real-time. Typical delivery: 2–15 seconds.
 
-2. **Polling fallback** — if WebSocket fails to connect or disconnects, automatically falls back to polling `GET /api/v1/order/{id}` every 5 seconds. Same result, slightly slower.
+2. **Polling fallback** — if WebSocket fails to connect or disconnects, automatically falls back to polling `GET /api/v1/order/{id}` every 5 seconds.
 
 The `delivery_method` field in the response tells you which was used.
 
 ### Architecture
 
 ```
-AI Agent (Claude/Cursor)
+AI Agent (Claude / Cursor / any MCP client)
     │
     ▼ MCP stdio protocol
 VirtualSMS MCP Server (this package)
     │
     ├──► REST API: https://virtualsms.io/api/v1/
-    │        buy_number, check_sms, cancel_order, etc.
+    │        buy_number, check_sms, cancel_order, get_balance ...
     │
     └──► WebSocket: wss://virtualsms.io/ws/orders
              real-time SMS push delivery
@@ -215,7 +255,7 @@ VirtualSMS MCP Server (this package)
 
 ## Typical Workflows
 
-### Simple: Get a Telegram code
+### Simple: Get a Telegram verification code
 ```
 wait_for_code(service: "telegram", country: "US")
 ```
@@ -231,35 +271,24 @@ wait_for_code(service: "telegram", country: "PK")
 ```
 buy_number(service: "google", country: "GB")
 # → order_id: "abc123", phone: "+447911123456"
-
-# Use the phone number to trigger the SMS...
-
+# Use the number to trigger the SMS, then:
 check_sms(order_id: "abc123")
-# Poll until sms_code appears, or:
-cancel_order(order_id: "abc123")  # if taking too long
+# or cancel if no longer needed:
+cancel_order(order_id: "abc123")
 ```
 
 ---
 
 ## Crash Recovery
 
-If your MCP server crashes or the AI session is interrupted mid-verification:
+If your session is interrupted mid-verification:
 
-1. **Restart the MCP server** (it reconnects automatically)
-2. **List active orders:**
-   ```
-   active_orders(status: "pending")
-   ```
-3. **Check for codes:**
-   ```
-   check_sms(order_id: "abc123")
-   ```
-4. **Cancel if no longer needed:**
-   ```
-   cancel_order(order_id: "abc123")
-   ```
+1. **Restart the MCP server**
+2. **List active orders:** `active_orders(status: "pending")`
+3. **Check for codes:** `check_sms(order_id: "abc123")`
+4. **Cancel if not needed:** `cancel_order(order_id: "abc123")`
 
-The `wait_for_code` tool always returns `order_id` even on timeout — this is your recovery handle.
+`wait_for_code` always returns `order_id` even on timeout — use it to recover.
 
 ---
 
@@ -267,4 +296,4 @@ The `wait_for_code` tool always returns `order_id` even on timeout — this is y
 
 MIT — See [LICENSE](./LICENSE)
 
-Built with ❤️ by [VirtualSMS.io](https://virtualsms.io)
+Built with ❤️ by [VirtualSMS.io](https://virtualsms.io) — virtual phone numbers for SMS verification, built on own infrastructure.

package/ROADMAP.md

@@ -46,3 +46,9 @@ Current version: **v1.0.0** — Core tools, WebSocket delivery, crash recovery.
 - **Rental numbers** — keep a number for days or weeks (not just one-time verification).
 - **Number recycling preferences** — opt out of recycled numbers for higher success rates.
 - **Operator filtering** — prefer specific carriers per country for higher deliverability.
+
+### Rental Tools (v1.1)
+- `rent_number` — Rent a number for days/weeks for recurring verifications
+- `extend_rental` — Extend an active rental period
+- `list_rentals` — List active number rentals
+- `rental_sms` — Check SMS received on a rented number

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "virtualsms-mcp",
-  "version": "1.0.0",
-  "description": "MCP server for VirtualSMS — receive SMS verification codes with AI agents",
+  "version": "1.0.2",
+  "description": "MCP server for VirtualSMS — receive SMS verification codes with AI agents. Virtual phone numbers and number rentals for WhatsApp, Telegram, Google & 200+ services. SMS-Activate & DaisySMS alternative.",
   "main": "dist/index.js",
   "bin": {
     "virtualsms-mcp": "dist/index.js"
@@ -14,22 +14,36 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "sms",
-    "verification",
+    "sms-verification",
+    "sms-activate",
     "virtual-number",
+    "virtual-phone-number",
     "phone-verification",
-    "sms-activate",
-    "model-context-protocol"
+    "receive-sms",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "daisysms-alternative",
+    "temporary-phone-number",
+    "whatsapp-verification",
+    "telegram-verification",
+    "virtualsms",
+    "phone-number-rental",
+    "long-term-virtual-number",
+    "sms-rental"
   ],
   "author": "VirtualSMS",
   "license": "MIT",
   "homepage": "https://virtualsms.io",
   "repository": {
     "type": "git",
-    "url": "https://github.com/virtualsms/mcp-server"
+    "url": "git+https://github.com/virtualsms-io/mcp-server.git"
   },
   "bugs": {
-    "url": "https://github.com/virtualsms/mcp-server/issues"
+    "url": "https://github.com/virtualsms-io/mcp-server/issues"
   },
   "engines": {
     "node": ">=18"