athenahealth MCP Server

Instructions

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), }, ], }; } }
• src/services/encounter-service.ts:5-30 (helper)

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