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:433-443 (handler)Handler case in CallToolRequestSchema that validates arguments and invokes the listAppointments function to execute the tool logic.
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:344-376 (helper)Core helper function that performs the API call to Cal.com to fetch and format appointments within the given date range.
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:247-257 (schema)Input argument validator (type guard) ensuring required startDate and endDate are present.
function isCalComListAppointmentsArgs(args: unknown): args is { startDate: string; endDate: string; } { return ( typeof args === "object" && args !== null && "startDate" in args && "endDate" in args ); } - index.ts:379-386 (registration)Registers the calcom_list_appointments tool (via LIST_APPOINTMENTS_TOOL) in the ListToolsRequestSchema handler.
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ ADD_APPOINTMENT_TOOL, UPDATE_APPOINTMENT_TOOL, DELETE_APPOINTMENT_TOOL, LIST_APPOINTMENTS_TOOL ], })); - index.ts:102-122 (schema)Tool definition including name, description, and input schema for validation.
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"], } };