searchPractitionersByName

Locate medical practitioners by entering their first name, last name, or a general name string using the Medplum MCP Server's search functionality.

Instructions

Searches for medical practitioners based on their given name, family name, or a general name string.

Input Schema

TableJSON Schema

Name	Required	Description
`familyName`	No	The practitioner's family (last) name.
`givenName`	No	The practitioner's given (first) name.
`name`	No	A general name search string for the practitioner.

Implementation Reference

src/tools/practitionerUtils.ts:17-38 (handler)

Core handler function that searches for Practitioner FHIR resources by constructing search parameters from givenName, familyName, or name, authenticates via Medplum, and executes the search.

export async function searchPractitionersByName(
  params: PractitionerNameSearchParams
): Promise<Practitioner[]> {
  await ensureAuthenticated();

  const searchCriteria: string[] = [];
  if (params.givenName) {
    searchCriteria.push(`given:contains=${params.givenName}`);
  }
  if (params.familyName) {
    searchCriteria.push(`family:contains=${params.familyName}`);
  }
  if (params.name) {
    searchCriteria.push(`name:contains=${params.name}`);
  }

  if (searchCriteria.length === 0) {
    return [];
  }
  const queryString = searchCriteria.join('&');
  return medplum.searchResources('Practitioner', queryString);
}

src/index.ts:193-213 (schema)

MCP input schema definition for the searchPractitionersByName tool, specifying parameters for givenName, familyName, and name.

  name: "searchPractitionersByName",
  description: "Searches for medical practitioners based on their given name, family name, or a general name string.",
  inputSchema: {
    type: "object",
    properties: {
      givenName: {
        type: "string",
        description: "The practitioner's given (first) name.",
      },
      familyName: {
        type: "string",
        description: "The practitioner's family (last) name.",
      },
      name: {
        type: "string",
        description: "A general name search string for the practitioner.",
      },
    },
    required: [],
  },
},

src/index.ts:950-988 (registration)

Tool mapping registration that associates the 'searchPractitionersByName' string key with the imported handler function for execution during tool calls.

const toolMapping: Record<string, (...args: any[]) => Promise<any>> = {
  createPatient,
  getPatientById, 
  updatePatient,
  searchPatients,
  searchPractitionersByName,
  createPractitioner,
  getPractitionerById,
  updatePractitioner,
  searchPractitioners,
  createOrganization,
  getOrganizationById,
  updateOrganization,
  searchOrganizations,
  createEncounter,
  getEncounterById,
  updateEncounter,
  searchEncounters,
  createObservation,
  getObservationById,
  updateObservation,
  searchObservations,
  createMedicationRequest,
  getMedicationRequestById,
  updateMedicationRequest,
  searchMedicationRequests,
  createMedication,
  getMedicationById,
  searchMedications,
  createEpisodeOfCare,
  getEpisodeOfCareById,
  updateEpisodeOfCare,
  searchEpisodesOfCare,
  createCondition,
  getConditionById,
  updateCondition,
  searchConditions,
  generalFhirSearch,
};

src/index.ts:14-19 (registration)

Import statement registering the searchPractitionersByName handler function from practitionerUtils into the main index file.

  searchPractitionersByName,
  createPractitioner,
  getPractitionerById,
  updatePractitioner,
  searchPractitioners,
} from './tools/practitionerUtils.js';

src/tools/toolSchemas.ts:1-23 (schema)

Original tool schema definition for searchPractitionersByName (likely legacy, as MCP uses inline schemas in index.ts).

export const toolSchemas = [
  {
    name: 'searchPractitionersByName',
    description: "Searches for medical practitioners (doctors, nurses, etc.) based on their given name, family name, or a general name string. Provide at least one name component.",
    input_schema: {
      type: 'object',
      properties: {
        givenName: {
          type: 'string',
          description: "The practitioner\'s given (first) name. Optional.",
        },
        familyName: {
          type: 'string',
          description: "The practitioner\'s family (last) name. Optional.",
        },
        name: {
          type: 'string',
          description: "A general name search string for the practitioner (e.g., \'Dr. John Smith\', \'Smith\'). Optional.",
        },
      },
      required: [], // Function logic handles requiring at least one param
    },
  },

Medplum MCP Server