Find available appointment slots

Instructions

Implementation Reference

• src/tools/find-available-slot.ts:28-84 (handler)

  Main handler function that finds available appointment slots for a given clinic, specialty, and date range. It iterates over providers, checks working hours, splits days into slots of the requested duration, filters out conflicts with existing appointments, and returns sorted results capped by the limit.

  export function findAvailableSlot(
    store: ClinicStore,
    raw: unknown,
  ): { slots: AvailableSlot[] } {
    const args = Args.parse(raw);
    const from = new Date(args.from_iso);
    const to = new Date(args.to_iso);
    if (Number.isNaN(from.getTime()) || Number.isNaN(to.getTime())) {
      throw new ValidationError("from_iso and to_iso must be valid ISO 8601");
    }
    if (from.getTime() >= to.getTime()) {
      throw new ValidationError("from_iso must be before to_iso");
    }
  
    const providers = store.listProviders(args.clinic_id, args.specialty);
    const slots: AvailableSlot[] = [];
  
    for (const provider of providers) {
      const existing = store
        .listProviderAppointments(args.clinic_id, provider.id)
        .map((a) => ({
          start: new Date(a.start_iso).getTime(),
          end: new Date(a.end_iso).getTime(),
        }));
  
      const startDay = startOfUtcDay(from);
      const endDay = startOfUtcDay(new Date(to.getTime() - 1));
  
      for (let day = startDay; day <= endDay; day += MS_PER_DAY) {
        const date = new Date(day);
        const weekday = date.getUTCDay();
        if (!provider.working_hours.days.includes(weekday)) continue;
  
        const dayStart =
          day + provider.working_hours.start_hour * 60 * MS_PER_MINUTE;
        const dayEnd =
          day + provider.working_hours.end_hour * 60 * MS_PER_MINUTE;
        const slotMs = args.duration_minutes * MS_PER_MINUTE;
  
        for (let s = dayStart; s + slotMs <= dayEnd; s += slotMs) {
          if (s < from.getTime() || s + slotMs > to.getTime()) continue;
          const conflicts = existing.some((a) => s < a.end && s + slotMs > a.start);
          if (conflicts) continue;
  
          slots.push({
            provider_id: provider.id,
            provider_name: provider.name,
            start_iso: new Date(s).toISOString(),
            end_iso: new Date(s + slotMs).toISOString(),
          });
        }
      }
    }
  
    slots.sort((a, b) => a.start_iso.localeCompare(b.start_iso));
    return { slots: slots.slice(0, args.limit) };
  }

• src/tools/find-available-slot.ts:6-13 (schema)

  Input schema definition using Zod — defines the input parameters: clinic_id, specialty, from_iso, to_iso, duration_minutes (default 30), and limit (default 10).

  export const findAvailableSlotInput = {
    clinic_id: z.string(),
    specialty: Specialty,
    from_iso: z.string().describe("Inclusive start of the search window, ISO 8601"),
    to_iso: z.string().describe("Exclusive end of the search window, ISO 8601"),
    duration_minutes: z.number().int().min(15).max(120).default(30),
    limit: z.number().int().min(1).max(50).default(10),
  };

• src/tools/find-available-slot.ts:18-23 (schema)

  TypeScript interface defining the output shape of each available slot returned by the handler.

  export interface AvailableSlot {
    provider_id: string;
    provider_name: string;
    start_iso: string;
    end_iso: string;
  }

• src/server.ts:50-59 (registration)

  Registration of the tool with the MCP server using registerTool, with title, description, input schema, and the handler wrapped in an error-handling wrapper.

  server.registerTool(
    "find_available_slot",
    {
      title: "Find available appointment slots",
      description:
        "Return open appointment slots for a given specialty in a date range. Filters by clinic_id and skips conflicts with existing appointments.",
      inputSchema: findAvailableSlotInput,
    },
    wrap((args) => findAvailableSlot(store, args)),
  );

• src/tools/find-available-slot.ts:86-88 (helper)

  Helper function that returns the epoch milliseconds for the start (midnight) of a given date's UTC day, used for day-by-day iteration in the handler.

  function startOfUtcDay(d: Date): number {
    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
  }