List Active Orders

Instructions

Implementation Reference

• src/tools.ts:1208-1238 (handler)

  The handler function `handleActiveOrders` that executes the 'virtualsms_list_orders' tool logic. It calls `client.listOrders(args.status)`, maps the results to a simplified format (order_id, phone_number, status, sms_code, sms_text, expires_at), and returns a JSON stringified response with a count and tip.

  export async function handleActiveOrders(
    client: VirtualSMSClient,
    args: z.infer<typeof ActiveOrdersInput>
  ) {
    const orders = await client.listOrders(args.status);
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(
            {
              count: orders.length,
              orders: orders.map((o) => ({
                order_id: o.order_id,
                phone_number: o.phone_number,
                status: o.status,
                sms_code: o.sms_code,
                sms_text: o.sms_text,
                expires_at: o.expires_at,
              })),
              tip: orders.length > 0
                ? 'Use check_sms with any order_id to get the latest status, or cancel_order to refund pending orders.'
                : 'No orders found.',
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools.ts:378-401 (schema)

  The tool definition/registration schema for 'virtualsms_list_orders' within the TOOL_DEFINITIONS array. Defines the name, title, description, inputSchema (optional status filter), and annotations including readOnlyHint and idempotentHint.

  {
    name: 'virtualsms_list_orders',
    title: 'List Active Orders',
    description:
      'List your active orders. Essential for crash recovery — if your session was interrupted, ' +
      'use this to find pending orders and their phone numbers, then use check_sms to retrieve codes.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        status: {
          type: 'string',
          description: 'Optional status filter: "pending", "sms_received", "cancelled", "completed"',
        },
      },
      required: [],
    },
    annotations: {
      title: 'List Active Orders',
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
  },

• src/tools.ts:48-50 (helper)

  The `ActiveOrdersInput` Zod schema used to validate the input parameters for the 'virtualsms_list_orders' tool. Defines an optional 'status' field for filtering by status (pending, sms_received, cancelled, completed).

  export const ActiveOrdersInput = z.object({
    status: z.string().optional().describe('Optional status filter: "pending", "sms_received", "cancelled", "completed"'),
  });

• src/index.ts:143-146 (registration)

  The registration in the main MCP server (stdio transport). The 'virtualsms_list_orders' case in the CallToolRequestSchema switch statement that parses args with ActiveOrdersInput and calls handleActiveOrders.

  case 'virtualsms_list_orders': {
    const parsed = ActiveOrdersInput.parse(args);
    return await handleActiveOrders(client, parsed);
  }

• src/http-server.ts:131-134 (registration)

  The registration in the HTTP server variant. The 'virtualsms_list_orders' case in the CallToolRequestSchema switch statement that parses args with ActiveOrdersInput and calls handleActiveOrders.

  case 'virtualsms_list_orders': {
    const parsed = ActiveOrdersInput.parse(args);
    return await handleActiveOrders(client, parsed);
  }