create_encounter

Instructions

Implementation Reference

• src/handlers/tool-handlers.ts:548-591 (handler)

  MCP tool handler that maps input arguments to encounter data, calls the AthenaHealth client to create the encounter, logs the action, and returns the result as JSON text content or error.

  async handleCreateEncounter(args: any) {
    try {
      const encounterData = {
        patientid: args.patient_id,
        departmentid: args.department_id,
        providerid: args.provider_id,
        encounterdate: args.encounter_date,
        encountertype: args.encounter_type,
        chiefcomplaint: args.chief_complaint,
        appointmentid: args.appointment_id,
      };
  
      const encounter = await this.client.createEncounter(encounterData);
  
      auditLog('ENCOUNTER_CREATE', {
        patientId: args.patient_id,
        result: 'success',
        resourceType: 'ENCOUNTER',
      });
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(encounter, null, 2),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              error: 'Failed to create encounter',
              message: error.message || 'Unknown error occurred',
              status: error.status || null,
              note: 'Encounter creation may not be available in the athenahealth preview/sandbox environment. This endpoint typically requires production API access.',
            }, null, 2),
          },
        ],
      };
    }
  }

• src/definitions/tools.ts:193-209 (schema)

  Tool definition including name, description, and input schema for validation of create_encounter parameters.

  {
    name: 'create_encounter',
    description: 'Create a new encounter for a patient',
    inputSchema: {
      type: 'object',
      properties: {
        patient_id: { type: 'string', description: 'Patient ID' },
        department_id: { type: 'string', description: 'Department ID' },
        provider_id: { type: 'string', description: 'Provider ID (optional)' },
        encounter_date: { type: 'string', description: 'Encounter date (YYYY-MM-DD)' },
        encounter_type: { type: 'string', description: 'Type of encounter (optional)' },
        chief_complaint: { type: 'string', description: 'Chief complaint (optional)' },
        appointment_id: { type: 'string', description: 'Associated appointment ID (optional)' },
      },
      required: ['patient_id', 'department_id', 'encounter_date'],
    },
  },

• src/mcp-server.ts:212-213 (registration)

  Dispatch case in MCP server request handler that routes create_encounter tool calls to the specific handler method.

  case 'create_encounter':
    return await this.toolHandlers.handleCreateEncounter(args);

• src/services/encounter-service.ts:39-66 (helper)

  Core service method that makes the actual POST request to AthenaHealth API to create the encounter using form-encoded data.

  async createEncounter(encounterData: {
    patientid: string;
    departmentid: string;
    providerid?: string;
    encounterdate: string;
    encountertype?: string;
    chiefcomplaint?: string;
    appointmentid?: string;
  }): Promise<Encounter> {
    const formData = new URLSearchParams();
    Object.entries(encounterData).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        formData.append(key, String(value));
      }
    });
  
    const response = await this.makeRequest<AthenaHealthResponse<Encounter>>(
      `${this.config.practice_id}/encounters`,
      {
        method: 'POST',
        data: formData.toString(),
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
        },
      }
    );
    return response.data || response;
  }