VirtualSMS MCP Server

Instructions

Implementation Reference

• src/tools.ts:765-805 (handler)

  The handleFindCheapest function implements the logic for searching and sorting countries by price for a specific service.

  export async function handleFindCheapest(
    client: VirtualSMSClient,
    args: z.infer<typeof FindCheapestInput>
  ) {
    const limit = args.limit ?? 5;
  
    const countries = await client.listCountries();
  
    const results: Array<{ country: string; country_name: string; price_usd: number; stock: boolean }> = [];
    const batchSize = 10;
  
    for (let i = 0; i < countries.length; i += batchSize) {
      const batch = countries.slice(i, i + batchSize);
      const priceChecks = await Promise.allSettled(
        batch.map(async (c) => {
          const price = await client.checkPrice(args.service, c.iso);
          return {
            country: c.iso,
            country_name: c.name,
            price_usd: price.price_usd,
            stock: price.available,
          };
        })
      );
  
      for (const result of priceChecks) {
        // Skip any country where the price check failed (404, unavailable, network error, etc.)
        if (result.status === 'fulfilled' && result.value.stock) {
          results.push(result.value);
        }
        // 'rejected' entries are silently skipped — invalid service/country combos
      }
    }
  
    results.sort((a, b) => a.price_usd - b.price_usd);
    const top = results.slice(0, limit);
  
    if (top.length === 0) {
      return {
        content: [
          {

• src/tools.ts:40-43 (schema)

  Zod schema definition for the input arguments of the find_cheapest_countries tool.

  export const FindCheapestInput = z.object({
    service: z.string().describe('Service code (e.g. "telegram", "whatsapp", "google")'),
    limit: z.number().int().min(1).max(50).default(5).describe('Number of cheapest options to return (default: 5)'),
  });

• src/tools.ts:269-289 (registration)

  Tool definition for 'find_cheapest_countries' in the tools configuration array.

  {
    name: 'find_cheapest_countries',
    title: 'Find Cheapest Countries',
    description:
      'Find the cheapest countries for a given service, sorted by price. ' +
      'Returns available countries with prices and stock levels so you can pick the best deal.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        service: {
          type: 'string',
          description: 'Service code (e.g. "telegram", "whatsapp", "google")',
        },
        limit: {
          type: 'number',
          description: 'Number of cheapest options to return (default: 5)',
          default: 5,
        },
      },
      required: ['service'],
    },