searchPatients

Instructions

Implementation Reference

• src/tools/patientUtils.ts:178-206 (handler)

  Core handler function for the 'searchPatients' tool. Builds FHIR search parameters from input args and performs the search using Medplum's searchResources method on Patient resources.

  export async function searchPatients(args: PatientSearchArgs): Promise<Patient[]> {
    await ensureAuthenticated();
    const searchCriteria: string[] = [];
  
    if (args.firstName) searchCriteria.push(`given:contains=${args.firstName}`);
    if (args.lastName) searchCriteria.push(`family:contains=${args.lastName}`);
    if (args.givenName) searchCriteria.push(`given:contains=${args.givenName}`);
    if (args.familyName) searchCriteria.push(`family:contains=${args.familyName}`);
    if (args.birthDate) searchCriteria.push(`birthdate=${args.birthDate}`);
    if (args.mrn) searchCriteria.push(`identifier=${args.mrn}`); // Assumes MRN is a primary identifier
    if (args.email) searchCriteria.push(`email=${args.email}`);
    if (args.telecom) searchCriteria.push(`telecom=${args.telecom}`);
    if (args.identifier) searchCriteria.push(`identifier=${args.identifier}`);
    if (args._lastUpdated) searchCriteria.push(`_lastUpdated=${args._lastUpdated}`);
  
    // Handle additional test fields
    if (args.family) searchCriteria.push(`family:contains=${args.family}`);
    if (args.given) searchCriteria.push(`given:contains=${args.given}`);
    if (args.birthdate) searchCriteria.push(`birthdate=${args.birthdate}`);
  
    if (searchCriteria.length === 0) {
      // Consider if this should throw an error, return all, or return empty.
      // Returning empty for now if no specific criteria are provided.
      return [];
    }
  
    const queryString = searchCriteria.join('&');
    return medplum.searchResources('Patient', queryString);
  }

• src/tools/patientUtils.ts:30-45 (schema)

  TypeScript interface defining the input parameters accepted by the searchPatients handler function.

  export interface PatientSearchArgs {
    firstName?: string;
    lastName?: string;
    birthDate?: string;
    mrn?: string;
    email?: string;
    telecom?: string;
    familyName?: string; // Added for more specific name search
    givenName?: string;  // Added for more specific name search
    identifier?: string; // General identifier search (e.g. system|value or just value)
    _lastUpdated?: string;
    // Add fields that tests expect
    family?: string;
    given?: string;
    birthdate?: string; // Alternative spelling used in tests
  }

• src/index.ts:164-190 (schema)

  MCP protocol input schema definition for the searchPatients tool, including properties for given name, family name, birthdate, and gender.

  {
    name: "searchPatients",
    description: "Searches for patients based on criteria like name or birth date.",
    inputSchema: {
      type: "object",
      properties: {
        given: {
          type: "string",
          description: "The patient's given (first) name.",
        },
        family: {
          type: "string", 
          description: "The patient's family (last) name.",
        },
        birthdate: {
          type: "string",
          description: "The patient's birth date in YYYY-MM-DD format.",
        },
        gender: {
          type: "string",
          description: "The patient's gender.",
          enum: ["male", "female", "other", "unknown"],
        },
      },
      required: [],
    },
  },

• src/index.ts:27-31 (registration)

  Import of the searchPatients handler function into the main index file for tool registration.

    createPatient,
    getPatientById,
    updatePatient,
    searchPatients,
  } from './tools/patientUtils.js';

• src/index.ts:954-954 (registration)

  Registration of the 'searchPatients' tool name mapped to its handler function in the toolMapping object used by the MCP server.

  searchPatients,