Medplum MCP Server

Instructions

Implementation Reference

• src/tools/practitionerUtils.ts:207-226 (handler)

  The handler function that implements the core logic for searching Practitioner resources using FHIR search parameters built from the input criteria via the Medplum client.

  export async function searchPractitioners(criteria: PractitionerSearchCriteria): Promise<Practitioner[]> {
    await ensureAuthenticated();
    const searchParams: string[] = [];
  
    if (criteria.identifier) searchParams.push(`identifier=${criteria.identifier}`);
    if (criteria.name) searchParams.push(`name:contains=${criteria.name}`);
    if (criteria.givenName) searchParams.push(`given:contains=${criteria.givenName}`);
    if (criteria.familyName) searchParams.push(`family:contains=${criteria.familyName}`);
    if (criteria.addressCity) searchParams.push(`address-city:contains=${criteria.addressCity}`);
    if (criteria.addressState) searchParams.push(`address-state:contains=${criteria.addressState}`);
    if (criteria.telecom) searchParams.push(`telecom=${criteria.telecom}`);
    if (criteria._lastUpdated) searchParams.push(`_lastUpdated=${criteria._lastUpdated}`);
    
    if (searchParams.length === 0) {
      return [];
    }
  
    const queryString = searchParams.join('&');
    return medplum.searchResources('Practitioner', queryString);
  } 

• src/index.ts:264-292 (schema)

  The MCP protocol input schema definition for the searchPractitioners tool, defining expected parameters for the tool call.

  {
    name: "searchPractitioners",
    description: "Searches for practitioners based on various criteria like name, specialty, or identifier.",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "A general name search string.",
        },
        given: {
          type: "string",
          description: "The practitioner's given (first) name.",
        },
        family: {
          type: "string",
          description: "The practitioner's family (last) name.",
        },
        specialty: {
          type: "string",
          description: "The practitioner's specialty (e.g., cardiology).",
        },
        identifier: {
          type: "string",
          description: "An identifier for the practitioner (e.g., NPI value).",
        },
      },
      required: [],
    },

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

  Import statement registering the searchPractitioners handler function from practitionerUtils into the main server index.

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

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

  Tool mapping that associates the tool name 'searchPractitioners' with its handler function for execution in the MCP server request handler.

  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/tools/practitionerUtils.ts:190-200 (helper)

  TypeScript interface defining the input criteria structure expected by the searchPractitioners handler.

  export interface PractitionerSearchCriteria {
    identifier?: string; // Search by identifier (e.g., NPI)
    name?: string;       // General name search
    givenName?: string;
    familyName?: string;
    addressCity?: string;
    addressState?: string;
    telecom?: string;
    _lastUpdated?: string;
    // Add other relevant criteria as needed
  }