athenahealth MCP Server

Instructions

Implementation Reference

• src/handlers/tool-handlers.ts:399-468 (handler)

  The primary handler function for the 'create_patient' tool. It maps tool arguments to patient data structure, removes undefined fields, invokes the Athenahealth client to create the patient, performs audit logging on success, and returns the patient object or a detailed error response in MCP content format.

  async handleCreatePatient(args: any) {
    try {
      console.error('handleCreatePatient received args:', JSON.stringify(args, null, 2));
  
      const patientData = {
        firstname: args.firstname,
        lastname: args.lastname,
        dob: args.dob,
        sex: args.sex,
        departmentid: args.department_id,
        email: args.email,
        mobilephone: args.mobile_phone,
        homephone: args.home_phone,
        address1: args.address1,
        city: args.city,
        state: args.state,
        zip: args.zip,
        guarantorfirstname: args.guarantor_firstname,
        guarantorlastname: args.guarantor_lastname,
        guarantordob: args.guarantor_dob,
        guarantorrelationshiptopatient: args.guarantor_relationship,
      };
  
      console.error('patientData before cleanup:', JSON.stringify(patientData, null, 2));
  
      // Remove undefined fields
      Object.keys(patientData).forEach(key => {
        if (patientData[key as keyof typeof patientData] === undefined) {
          delete patientData[key as keyof typeof patientData];
        }
      });
  
      console.error('patientData after cleanup:', JSON.stringify(patientData, null, 2));
  
      const patient = await this.client.createPatient(patientData);
  
      auditLog('PATIENT_CREATE', {
        result: 'success',
        resourceType: 'PATIENT',
      });
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(patient, null, 2),
          },
        ],
      };
    } catch (error: any) {
      console.error('Create patient error:', error);
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              error: 'Failed to create patient',
              message: error.message || 'Unknown error occurred',
              error_code: error.error || null,
              detailcode: error.detailcode || null,
              api_details: error.details || null,
              api_response: error.response || null,
              status_code: error.status || null,
              note: 'Check the api_response field for specific validation errors from athenahealth',
            }, null, 2),
          },
        ],
      };
    }
  }

• src/definitions/tools.ts:142-166 (schema)

  Defines the tool metadata including name, description, and detailed input schema with required and optional parameters for creating a patient.

    name: 'create_patient',
    description: 'Register a new patient in the system',
    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 (MM/DD/YYYY or YYYY-MM-DD)' },
        sex: { type: 'string', description: 'Sex (M or F)' },
        department_id: { type: 'string', description: 'Primary department ID' },
        email: { type: 'string', description: 'Email address (optional)' },
        mobile_phone: { type: 'string', description: 'Mobile phone number (optional)' },
        home_phone: { type: 'string', description: 'Home phone number (optional)' },
        address1: { type: 'string', description: 'Street address (optional)' },
        city: { type: 'string', description: 'City (optional)' },
        state: { type: 'string', description: 'State (optional)' },
        zip: { type: 'string', description: 'ZIP code (optional)' },
        guarantor_firstname: { type: 'string', description: 'Guarantor first name (optional)' },
        guarantor_lastname: { type: 'string', description: 'Guarantor last name (optional)' },
        guarantor_dob: { type: 'string', description: 'Guarantor date of birth (optional)' },
        guarantor_relationship: { type: 'string', description: 'Relationship to patient: 1=Self, 2=Spouse, 3=Child, 4=Other (optional)' },
      },
      required: ['firstname', 'lastname', 'dob', 'sex', 'department_id'],
    },
  },

• src/mcp-server.ts:203-204 (registration)

  Dispatches the 'create_patient' tool call to the corresponding handler method in the MCP server implementation.

  case 'create_patient':
    return await this.toolHandlers.handleCreatePatient(args);