search_patients

Instructions

Implementation Reference

• src/handlers/tool-handlers.ts:7-84 (handler)

  The main MCP tool handler for search_patients. Validates input parameters, calls the AthenaHealthClient to search patients, handles errors, logs activity, and formats the response as MCP content.

  async handleSearchPatients(args: any) {
    try {
      // Validate that at least one search parameter is provided
      const searchFields = ['firstname', 'lastname', 'dob', 'departmentid', 'phone', 'email'];
      const hasSearchParam = searchFields.some(field => args[field]);
  
      if (!hasSearchParam) {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                error: 'At least one search parameter is required',
                message: 'Please provide at least one of: firstname, lastname, dob, departmentid, phone, or email',
                example: {
                  firstname: 'John',
                  lastname: 'Doe',
                  limit: 10
                }
              }, null, 2),
            },
          ],
        };
      }
  
      const patients = await this.client.searchPatients(args);
  
      // Log the actual response for debugging
      console.error('Patient search raw response:', JSON.stringify(patients, null, 2));
      console.error('Response type:', typeof patients);
      console.error('Is array:', Array.isArray(patients));
  
      auditLog('PATIENT_SEARCH', { result: 'success' });
  
      if (!patients || typeof patients.length !== 'number') {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                error: 'Patient search failed',
                message: 'The API returned an unexpected response.',
                suggestion: 'Try using list_departments first to get department IDs, then use list_patients_by_department to list patients.',
                api_response: patients,
                response_type: typeof patients,
                is_array: Array.isArray(patients),
              }, null, 2),
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify(patients, null, 2),
          },
        ],
      };
    } catch (error: any) {
      console.error('handleSearchPatients caught error:', error);
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              error: 'Patient search exception',
              message: error.message || 'Unknown error occurred',
              error_type: error.error || 'Unknown',
              details: error.details || error.message,
              detailcode: error.detailcode,
            }, null, 2),
          },
        ],
      };
    }
  }

• src/definitions/tools.ts:4-19 (schema)

  Input schema and metadata definition for the search_patients tool, used for MCP tool listing and validation.

  {
    name: 'search_patients',
    description: 'Search for patients by name, DOB, phone, or email',
    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 (YYYY-MM-DD)' },
        phone: { type: 'string', description: 'Phone number' },
        email: { type: 'string', description: 'Email address' },
        limit: { type: 'number', description: 'Maximum number of results', default: 10 },
      },
      required: [],
    },
  },

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

  Registers the tool definitions (including search_patients) for MCP's listTools request handler.

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

• src/mcp-server.ts:176-178 (registration)

  Dispatches incoming search_patients tool calls to the ToolHandlers.handleSearchPatients method.

  case 'search_patients':
    return await this.toolHandlers.handleSearchPatients(args);

• src/services/patient-service.ts:5-49 (helper)

  Core service method that makes the actual AthenaHealth API GET request to /patients with search parameters and normalizes the response.

  async searchPatients(params: {
    firstname?: string;
    lastname?: string;
    dob?: string;
    phone?: string;
    email?: string;
    limit?: number;
  }): Promise<Patient[]> {
    try {
      const queryParams: any = {};
  
      if (params.firstname) queryParams.firstname = params.firstname;
      if (params.lastname) queryParams.lastname = params.lastname;
      if (params.dob) queryParams.dob = params.dob;
      if (params.phone) queryParams.phone = params.phone;
      if (params.email) queryParams.email = params.email;
      if (params.limit) queryParams.limit = params.limit;
  
      const response = await this.makeRequest<any>(
        `${this.config.practice_id}/patients`,
        {
          method: 'GET',
          params: queryParams,
        }
      );
  
      if (response.patients && Array.isArray(response.patients)) {
        return response.patients;
      }
  
      if (Array.isArray(response)) {
        return response;
      }
  
      if (response.data && Array.isArray(response.data)) {
        return response.data;
      }
  
      console.error('Unexpected patients response structure, returning empty array');
      return [];
    } catch (error: any) {
      console.error('Search patients error:', error.message);
      throw error;
    }
  }