Medplum MCP Server

Instructions

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
      },
    },