search_patients
Find patients in the athenahealth system using name, date of birth, phone number, or email address to quickly locate medical records and support clinical workflows.
Instructions
Search for patients by name, DOB, phone, or email
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dob | No | Date of birth (YYYY-MM-DD) | |
| No | Email address | ||
| firstname | No | Patient first name | |
| lastname | No | Patient last name | |
| limit | No | Maximum number of results | |
| phone | No | Phone number |
Implementation Reference
- src/handlers/tool-handlers.ts:7-84 (handler)MCP tool handler that validates arguments, calls the AthenaHealth client to search patients, handles errors, logs access, and formats the JSON response for the MCP protocol.async handleSearchPatients(args: any) { try { // Validate that at least one search parameter is provided const searchFields = ['firstname', 'lastname', 'dob', 'departmentid', 'phone', 'email']; const hasSearchParam = searchFields.some(field => args[field]); if (!hasSearchParam) { return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'At least one search parameter is required', message: 'Please provide at least one of: firstname, lastname, dob, departmentid, phone, or email', example: { firstname: 'John', lastname: 'Doe', limit: 10 } }, null, 2), }, ], }; } const patients = await this.client.searchPatients(args); // Log the actual response for debugging console.error('Patient search raw response:', JSON.stringify(patients, null, 2)); console.error('Response type:', typeof patients); console.error('Is array:', Array.isArray(patients)); auditLog('PATIENT_SEARCH', { result: 'success' }); if (!patients || typeof patients.length !== 'number') { return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'Patient search failed', message: 'The API returned an unexpected response.', suggestion: 'Try using list_departments first to get department IDs, then use list_patients_by_department to list patients.', api_response: patients, response_type: typeof patients, is_array: Array.isArray(patients), }, null, 2), }, ], }; } return { content: [ { type: 'text' as const, text: JSON.stringify(patients, null, 2), }, ], }; } catch (error: any) { console.error('handleSearchPatients caught error:', error); return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'Patient search exception', message: error.message || 'Unknown error occurred', error_type: error.error || 'Unknown', details: error.details || error.message, detailcode: error.detailcode, }, null, 2), }, ], }; } }
- src/definitions/tools.ts:4-19 (schema)Tool schema definition including name, description, and input schema for validating search parameters like firstname, lastname, dob, etc.{ name: 'search_patients', description: 'Search for patients by name, DOB, phone, or email', inputSchema: { type: 'object', properties: { firstname: { type: 'string', description: 'Patient first name' }, lastname: { type: 'string', description: 'Patient last name' }, dob: { type: 'string', description: 'Date of birth (YYYY-MM-DD)' }, phone: { type: 'string', description: 'Phone number' }, email: { type: 'string', description: 'Email address' }, limit: { type: 'number', description: 'Maximum number of results', default: 10 }, }, required: [], }, },
- src/mcp-server.ts:176-178 (registration)Registration in the MCP server's tool call handler switch statement that dispatches 'search_patients' calls to the ToolHandlers.handleSearchPatients method.case 'search_patients': return await this.toolHandlers.handleSearchPatients(args);
- src/services/patient-service.ts:4-49 (helper)Service class method implementing the core API call to AthenaHealth /patients endpoint with query parameters for searching patients, handling various response formats.export class PatientService extends BaseAthenaClient { async searchPatients(params: { firstname?: string; lastname?: string; dob?: string; phone?: string; email?: string; limit?: number; }): Promise<Patient[]> { try { const queryParams: any = {}; if (params.firstname) queryParams.firstname = params.firstname; if (params.lastname) queryParams.lastname = params.lastname; if (params.dob) queryParams.dob = params.dob; if (params.phone) queryParams.phone = params.phone; if (params.email) queryParams.email = params.email; if (params.limit) queryParams.limit = params.limit; const response = await this.makeRequest<any>( `${this.config.practice_id}/patients`, { method: 'GET', params: queryParams, } ); if (response.patients && Array.isArray(response.patients)) { return response.patients; } if (Array.isArray(response)) { return response; } if (response.data && Array.isArray(response.data)) { return response.data; } console.error('Unexpected patients response structure, returning empty array'); return []; } catch (error: any) { console.error('Search patients error:', error.message); throw error; } }