athenahealth MCP Server

Instructions

Implementation Reference

• src/handlers/tool-handlers.ts:215-304 (handler)

  The primary handler function for the get_clinical_summary tool. It fetches patient demographics and optionally allergies, problems, prescriptions, vitals, labs, and alerts from AthenaHealth API, handles errors gracefully for sandbox limitations, logs data access, and returns a JSON-formatted summary.

  async handleGetClinicalSummary(args: any) {
    const { patient_id, ...options } = args;
    const summary: any = {};
    const errors: any = {};
  
    // Get patient details
    try {
      summary.patient = await this.client.getPatient(patient_id);
    } catch (error: any) {
      errors.patient = error.message || 'Failed to fetch patient data';
    }
  
    // Get clinical data based on options - handle errors gracefully
    const warnings: string[] = [];
  
    if (options.include_allergies !== false) {
      try {
        summary.allergies = await this.client.getPatientAllergies(patient_id);
      } catch (error: any) {
        warnings.push('Allergies endpoint not available in preview/sandbox');
        summary.allergies = [];
      }
    }
  
    if (options.include_problems !== false) {
      try {
        summary.problems = await this.client.getPatientProblems(patient_id);
      } catch (error: any) {
        warnings.push('Problems endpoint not available in preview/sandbox');
        summary.problems = [];
      }
    }
  
    if (options.include_prescriptions !== false) {
      try {
        summary.prescriptions = await this.client.getPatientPrescriptions(patient_id);
      } catch (error: any) {
        warnings.push('Prescriptions endpoint not available in preview/sandbox');
        summary.prescriptions = [];
      }
    }
  
    if (options.include_vitals !== false) {
      try {
        summary.vitals = await this.client.getPatientVitals(patient_id);
      } catch (error: any) {
        warnings.push('Vitals endpoint not available in preview/sandbox');
        summary.vitals = [];
      }
    }
  
    if (options.include_labs !== false) {
      try {
        summary.labs = await this.client.getPatientLabResults(patient_id);
      } catch (error: any) {
        warnings.push('Labs endpoint not available in preview/sandbox');
        summary.labs = [];
      }
    }
  
    if (options.include_alerts !== false) {
      try {
        summary.alerts = await this.client.getClinicalAlerts(patient_id);
      } catch (error: any) {
        warnings.push('Alerts endpoint not available in preview/sandbox');
        summary.alerts = [];
      }
    }
  
    // Include warnings and errors
    if (warnings.length > 0) {
      summary._warnings = warnings;
      summary._note = 'Preview/Sandbox environment: Clinical endpoints unavailable. Only patient demographics accessible.';
    }
  
    if (Object.keys(errors).length > 0) {
      summary._errors = errors;
    }
  
    logDataAccess('CLINICAL_SUMMARY', patient_id, 'READ');
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(summary, null, 2),
        },
      ],
    };
  }

• src/definitions/tools.ts:87-103 (schema)

  Tool definition including name, description, and input schema specifying patient_id as required and optional boolean flags to include various clinical data sections.

  {
    name: 'get_clinical_summary',
    description: 'Get a comprehensive clinical summary for a patient',
    inputSchema: {
      type: 'object',
      properties: {
        patient_id: { type: 'string', description: 'Patient ID' },
        include_allergies: { type: 'boolean', description: 'Include allergies', default: true },
        include_problems: { type: 'boolean', description: 'Include problems', default: true },
        include_prescriptions: { type: 'boolean', description: 'Include prescriptions', default: true },
        include_vitals: { type: 'boolean', description: 'Include vitals', default: true },
        include_labs: { type: 'boolean', description: 'Include lab results', default: true },
        include_alerts: { type: 'boolean', description: 'Include clinical alerts', default: true },
      },
      required: ['patient_id'],
    },
  },

• src/mcp-server.ts:191-192 (registration)

  Registration in the MCP server tool call handler switch statement, dispatching calls to the toolHandlers.handleGetClinicalSummary method.

  case 'get_clinical_summary':
    return await this.toolHandlers.handleGetClinicalSummary(args);

• src/mcp-server.ts:166-168 (registration)

  Tool list request handler that returns the toolDefinitions array, making get_clinical_summary available to MCP clients.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools: toolDefinitions };
  });