searchPatients
Search for patients in the Medplum MCP Server by criteria such as name, birth date, or gender to efficiently manage healthcare data and streamline patient retrieval.
Instructions
Searches for patients based on criteria like name or birth date.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| birthdate | No | The patient's birth date in YYYY-MM-DD format. | |
| family | No | The patient's family (last) name. | |
| gender | No | The patient's gender. | |
| given | No | The patient's given (first) name. |
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,