Medplum MCP Server

Instructions

Implementation Reference

• src/tools/practitionerUtils.ts:63-122 (handler)

  The handler function that implements the core logic for creating a FHIR Practitioner resource using Medplum client. Handles input validation, backward compatibility for field names, constructs the resource, and calls createResource.

  export async function createPractitioner(args: CreatePractitionerArgs): Promise<Practitioner> {
    await ensureAuthenticated();
  
    // Handle backward compatibility
    let family = args.family;
    let given = args.given;
    
    if (args.familyName && !family) {
      family = args.familyName;
    }
    if (args.givenName && (!given || given.length === 0)) {
      given = [args.givenName];
    }
  
    if (!family) {
      throw new Error('Family name is required to create a practitioner.');
    }
    if (!given || given.length === 0) {
      throw new Error('At least one given name is required to create a practitioner.');
    }
  
    const practitionerResource: Practitioner = {
      resourceType: 'Practitioner',
      name: [{
        family: family,
        given: given,
      }],
      active: true,
    };
  
    // Handle identifier (now an array)
    if (args.identifier && args.identifier.length > 0) {
      practitionerResource.identifier = args.identifier;
    }
  
    // Handle telecom directly if provided
    if (args.telecom && args.telecom.length > 0) {
      practitionerResource.telecom = args.telecom;
    }
  
    // Handle other fields
    if (args.gender) {
      practitionerResource.gender = args.gender;
    }
    if (args.birthDate) {
      practitionerResource.birthDate = args.birthDate;
    }
    if (args.qualification) {
      practitionerResource.qualification = [{ code: { text: args.qualification } }];
    }
  
    // Allow setting active status on create
    if (typeof args.active === 'boolean') {
      practitionerResource.active = args.active;
    } else {
      practitionerResource.active = true; // Default to true if not specified
    }
  
    return medplum.createResource<Practitioner>(practitionerResource);
  }

• src/tools/practitionerUtils.ts:42-56 (schema)

  TypeScript interface defining the input arguments for the createPractitioner handler, including optional fields for FHIR Practitioner properties and backward compatibility.

  export interface CreatePractitionerArgs {
    family?: string;
    given?: string[]; 
    gender?: 'male' | 'female' | 'other' | 'unknown';
    birthDate?: string;
    // phone?: string; // Deprecate in favor of telecom array
    // email?: string; // Deprecate in favor of telecom array
    telecom?: ContactPoint[]; // Added for FHIR alignment and test compatibility
    qualification?: string;
    identifier?: Identifier[];
    active?: boolean; // Allow setting active status on create
    // Backward compatibility fields
    givenName?: string;
    familyName?: string;
  }

• src/index.ts:214-231 (schema)

  MCP protocol input schema for the createPractitioner tool, defining required givenName and familyName parameters.

  {
    name: "createPractitioner",
    description: "Creates a new medical practitioner. Requires given name and family name.",
    inputSchema: {
      type: "object",
      properties: {
        givenName: {
          type: "string",
          description: "The practitioner's given (first) name.",
        },
        familyName: {
          type: "string",
          description: "The practitioner's family (last) name.",
        },
      },
      required: ["givenName", "familyName"],
    },
  },

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

  Maps the tool name 'createPractitioner' to its handler function for execution in the MCP callTool 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/index.ts:14-19 (registration)

  Imports the createPractitioner handler from practitionerUtils.ts for use in the MCP server.

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