get_patient_encounters
Retrieve patient encounter records from athenahealth to review medical visits, treatments, and clinical history for care coordination and documentation.
Instructions
Get all encounters for a patient
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| patient_id | Yes | Patient ID | |
| department_id | No | Filter by department ID (optional) | |
| start_date | No | Start date filter (YYYY-MM-DD) (optional) | |
| end_date | No | End date filter (YYYY-MM-DD) (optional) | |
| status | No | Filter by status: OPEN, CLOSED, SIGNED (optional) |
Implementation Reference
- src/definitions/tools.ts:167-181 (schema)Tool schema definition with input validation schema for get_patient_encounters
{ name: 'get_patient_encounters', description: 'Get all encounters for a patient', inputSchema: { type: 'object', properties: { patient_id: { type: 'string', description: 'Patient ID' }, department_id: { type: 'string', description: 'Filter by department ID (optional)' }, start_date: { type: 'string', description: 'Start date filter (YYYY-MM-DD) (optional)' }, end_date: { type: 'string', description: 'End date filter (YYYY-MM-DD) (optional)' }, status: { type: 'string', description: 'Filter by status: OPEN, CLOSED, SIGNED (optional)' }, }, required: ['patient_id'], }, }, - src/mcp-server.ts:206-207 (registration)Registration and dispatch of get_patient_encounters tool call to the handler in MCP server
case 'get_patient_encounters': return await this.toolHandlers.handleGetPatientEncounters(args); - src/handlers/tool-handlers.ts:470-510 (handler)Primary handler function executing the tool: extracts parameters, calls AthenaHealthClient, audits access, returns JSON response or error
async handleGetPatientEncounters(args: any) { try { const { patient_id, department_id, start_date, end_date, status } = args; const encounters = await this.client.getPatientEncounters(patient_id, { departmentid: department_id, startdate: start_date, enddate: end_date, status, }); auditLog('ENCOUNTER_ACCESS', { patientId: patient_id, result: 'success', resourceType: 'ENCOUNTER', }); return { content: [ { type: 'text' as const, text: JSON.stringify(encounters, null, 2), }, ], }; } catch (error: any) { return { content: [ { type: 'text' as const, text: JSON.stringify({ error: 'Failed to get patient encounters', message: error.message || 'Unknown error occurred', status: error.status || null, note: 'Encounter endpoints may not be available in the athenahealth preview/sandbox environment.', }, null, 2), }, ], }; } } - Core service implementation making the HTTP GET request to Athenahealth API for patient encounters and handling response normalization
async getPatientEncounters(patientId: string, params?: { departmentid?: string; startdate?: string; enddate?: string; status?: string; }): Promise<Encounter[]> { const response = await this.makeRequest<any>( `${this.config.practice_id}/patients/${patientId}/encounters`, { method: 'GET', params, } ); // Handle different response structures if (response.encounters && Array.isArray(response.encounters)) { return response.encounters; } if (Array.isArray(response)) { return response; } if (response.data && Array.isArray(response.data)) { return response.data; } return []; }