check_appointment_availability
Find available appointment slots for a specific department within a date range to schedule patient visits efficiently.
Instructions
Check available appointment slots for a department and date range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| department_id | Yes | Department ID | |
| provider_id | No | Provider ID (optional - leave empty to check all providers) | |
| appointment_type | No | Appointment type (optional) | |
| start_date | Yes | Start date (YYYY-MM-DD) | |
| end_date | Yes | End date (YYYY-MM-DD) |
Implementation Reference
- src/handlers/tool-handlers.ts:362-397 (handler)The primary MCP tool handler function that processes the tool call, extracts parameters, calls the service client, and formats the response as MCP content.
async handleCheckAppointmentAvailability(args: any) { try { const { department_id, provider_id, appointment_type, start_date, end_date } = args; const availability = await this.client.getAppointmentAvailability({ departmentid: department_id, providerid: provider_id, appointmenttype: appointment_type, startdate: start_date, enddate: end_date, }); return { content: [ { type: 'text' as const, text: JSON.stringify(availability, null, 2), }, ], }; } catch (error: any) { return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'Failed to check appointment availability', message: error.message || 'Unknown error occurred', details: error.details || error.message, note: 'This endpoint may not be available in the preview/sandbox environment', }, null, 2), }, ], }; } } - src/definitions/tools.ts:126-140 (schema)The input schema and metadata definition for the check_appointment_availability tool, used for validation and tool listing.
{ name: 'check_appointment_availability', description: 'Check available appointment slots for a department and date range', inputSchema: { type: 'object', properties: { department_id: { type: 'string', description: 'Department ID' }, provider_id: { type: 'string', description: 'Provider ID (optional - leave empty to check all providers)' }, appointment_type: { type: 'string', description: 'Appointment type (optional)' }, start_date: { type: 'string', description: 'Start date (YYYY-MM-DD)' }, end_date: { type: 'string', description: 'End date (YYYY-MM-DD)' }, }, required: ['department_id', 'start_date', 'end_date'], }, }, - src/mcp-server.ts:200-201 (registration)Tool dispatch registration in the MCP server's CallToolRequest handler switch statement.
case 'check_appointment_availability': return await this.toolHandlers.handleCheckAppointmentAvailability(args); - Supporting service method that performs the actual HTTP request to the Athenahealth API /appointments/open endpoint to retrieve available slots.
async getAppointmentAvailability(params: { departmentid: string; startdate: string; enddate: string; providerid?: string; appointmenttype?: string; }): Promise<any[]> { try { const response = await this.makeRequest<any>( `${this.config.practice_id}/appointments/open`, { method: 'GET', params, } ); if (response.appointments && Array.isArray(response.appointments)) { return response.appointments; } if (Array.isArray(response)) { return response; } if (response.data && Array.isArray(response.data)) { return response.data; } return []; } catch (error: any) { console.error('Get appointment availability error:', error.message); throw error; } }