search_patients
Find patients in athenahealth using name, date of birth, phone number, or email address to support clinical workflows and data access.
Instructions
Search for patients by name, DOB, phone, or email
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| firstname | No | Patient first name | |
| lastname | No | Patient last name | |
| dob | No | Date of birth (YYYY-MM-DD) | |
| phone | No | Phone number | |
| No | Email address | ||
| limit | No | Maximum number of results |
Implementation Reference
- src/handlers/tool-handlers.ts:7-84 (handler)The main MCP tool handler for search_patients. Validates input parameters, calls the AthenaHealthClient to search patients, handles errors, logs activity, and formats the response as MCP content.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)Input schema and metadata definition for the search_patients tool, used for MCP tool listing and validation.{ 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:166-169 (registration)Registers the tool definitions (including search_patients) for MCP's listTools request handler.this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: toolDefinitions }; });
- src/mcp-server.ts:176-178 (registration)Dispatches incoming search_patients tool calls to the ToolHandlers.handleSearchPatients method.case 'search_patients': return await this.toolHandlers.handleSearchPatients(args);
- src/services/patient-service.ts:5-49 (helper)Core service method that makes the actual AthenaHealth API GET request to /patients with search parameters and normalizes the response.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; } }