calcom_list_appointments
Retrieve scheduled appointments from Cal.com calendar within a specified date range to view upcoming meetings and events.
Instructions
Lists appointments from Cal.com calendar. Can be filtered by date range. Returns a list of appointments with their details.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | Yes | Start date in YYYY-MM-DD format | |
| endDate | Yes | End date in YYYY-MM-DD format |
Implementation Reference
- index.ts:344-376 (handler)The core handler function that queries the Cal.com API for bookings in the given date range, formats the results into a readable text summary, and handles errors.async function listAppointments(startDate: string, endDate: string) { checkRateLimit(); try { const response = await calComApiClient.get('/bookings', { params: { dateFrom: startDate, dateTo: endDate, } }); const bookings = response.data; if (bookings.length === 0) { return "No appointments found for the selected date range."; } return bookings.map((booking: any) => ` ID: ${booking.id} Event Type: ${booking.eventTypeId} Status: ${booking.status} Start Time: ${booking.startTime} End Time: ${booking.endTime} Attendees: ${booking.attendees.map((a: any) => `${a.name} (${a.email})`).join(", ")} ${booking.notes ? `Notes: ${booking.notes}` : ""} `).join("\n---\n"); } catch (error: any) { if (axios.isAxiosError(error)) { throw new Error(`Failed to list appointments: ${error.response?.data?.message || error.message}`); } throw new Error(`Failed to list appointments: ${String(error)}`); } }
- index.ts:102-122 (registration)Defines the tool registration including name, description, and input schema for listing appointments.const LIST_APPOINTMENTS_TOOL: Tool = { name: "calcom_list_appointments", description: "Lists appointments from Cal.com calendar. " + "Can be filtered by date range. " + "Returns a list of appointments with their details. ", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format" }, endDate: { type: "string", description: "End date in YYYY-MM-DD format" } }, required: ["startDate", "endDate"], } };
- index.ts:247-257 (schema)Type guard function that validates the input arguments match the expected schema for calcom_list_appointments.function isCalComListAppointmentsArgs(args: unknown): args is { startDate: string; endDate: string; } { return ( typeof args === "object" && args !== null && "startDate" in args && "endDate" in args ); }
- index.ts:433-443 (handler)The dispatch handler in the main CallToolRequestSchema that validates args and calls the listAppointments function.case "calcom_list_appointments": { if (!isCalComListAppointmentsArgs(args)) { throw new Error("Invalid arguments for calcom_list_appointments"); } const { startDate, endDate } = args; const result = await listAppointments(startDate, endDate); return { content: [{ type: "text", text: result }], isError: false, }; }
- index.ts:379-386 (registration)Registers all tools, including calcom_list_appointments, in the ListToolsRequest handler.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ ADD_APPOINTMENT_TOOL, UPDATE_APPOINTMENT_TOOL, DELETE_APPOINTMENT_TOOL, LIST_APPOINTMENTS_TOOL ], }));