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
`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);
```

src/services/scheduling-service.ts:90-123 (helper)

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;
  }
}

athenahealth MCP Server