Medplum MCP Server

Instructions

Implementation Reference

• src/tools/encounterUtils.ts:151-185 (handler)

  Core handler function that performs the updateEncounter tool logic: authenticates, validates inputs, reads existing Encounter, applies updates (with class handling), and updates via Medplum.
  export async function updateEncounter(encounterId: string, updates: UpdateEncounterArgs): Promise<Encounter> { await ensureAuthenticated(); if (!encounterId) { throw new Error('Encounter ID is required to update an encounter.'); } if (!updates || Object.keys(updates).length === 0) { throw new Error('Updates object cannot be empty for updating an encounter.'); } const existingEncounter = await medplum.readResource('Encounter', encounterId); if (!existingEncounter) { throw new Error(`Encounter with ID ${encounterId} not found.`); } const { resourceType, id, ...safeUpdates } = updates as any; // Handle class conversion if (typeof safeUpdates.class === 'string') { safeUpdates.class = mapEncounterClass(safeUpdates.class); } if (updates.classCode) { safeUpdates.class = mapEncounterClass(updates.classCode); delete safeUpdates.classCode; // Remove the convenience field } const encounterToUpdate: Encounter = { ...existingEncounter, ...safeUpdates, resourceType: 'Encounter', id: encounterId, }; return medplum.updateResource(encounterToUpdate); }
• src/tools/toolSchemas.ts:361-407 (schema)

  Detailed input schema definition for the updateEncounter tool, including properties for encounterId and updates object with examples for common fields like status, class, period.
  { name: 'updateEncounter', description: 'Updates an existing encounter. Requires the encounter ID and an object containing the fields to update.', input_schema: { type: 'object', properties: { encounterId: { type: 'string', description: 'The unique ID of the encounter to update.', }, updates: { type: 'object', description: "An object containing the encounter fields to update. Refer to the Encounter FHIR resource definition for possible fields. For example, to update status: { \"status\": \"in-progress\" }. For fields like 'class' or 'type', you can provide a simple code (e.g., { \"class\": \"IMP\" }) or the full FHIR Coding/CodeableConcept structure if needed for precision.", properties: { // Define common, simple updatable fields here to guide the LLM. // More complex structures can be passed, and the description guides the LLM. status: { type: 'string', description: "Update the status of the encounter (e.g., planned, in-progress, finished). Optional.", enum: ['planned', 'arrived', 'triaged', 'in-progress', 'onleave', 'finished', 'cancelled', 'entered-in-error', 'unknown'], }, class: { type: ['string', 'object'], // Can be a simple code string or a FHIR Coding object description: "Update the class of the encounter (e.g., AMB, IMP, EMER as a string, or a FHIR Coding object). Optional.", }, // For 'type' (CodeableConcept[]), it's harder to simplify for LLM updates via simple properties. // The main 'updates' description guides it to provide FHIR structure or simple type code string within the type array. // Example: updates: { type: [{ coding: [{ system: 'some-system', code: 'XYZ' }] }] } or potentially simplified if handled by util. periodStart: { type: 'string', format: 'date-time', description: "Update the start date and time of the encounter (ISO8601 format). Optional.", }, periodEnd: { type: 'string', format: 'date-time', description: "Update the end date and time of the encounter (ISO8601 format). Optional.", }, // Add other commonly updated simple fields as necessary. // For complex fields like 'participant', 'reasonCode', 'hospitalization', the LLM should provide them // directly in the 'updates' object matching FHIR structure, guided by the main description. }, additionalProperties: true, // Allows other FHIR fields not explicitly listed here }, }, required: ['encounterId', 'updates'], },
• src/index.ts:415-433 (registration)

  MCP tool registration in mcpTools array, providing name, description, and simplified inputSchema for listTools request.
  { name: "updateEncounter", description: "Updates an existing encounter. Requires the encounter ID and the fields to update.", inputSchema: { type: "object", properties: { encounterId: { type: "string", description: "The unique ID of the encounter to update.", }, status: { type: "string", description: "New status for the encounter.", enum: ["planned", "arrived", "triaged", "in-progress", "onleave", "finished", "cancelled"], }, }, required: ["encounterId"], }, },
• src/index.ts:33-37 (registration)

  Import of the updateEncounter handler function from encounterUtils into the main index.ts for use in toolMapping.
  createEncounter, getEncounterById, updateEncounter, searchEncounters, } from './tools/encounterUtils.js';
• src/index.ts:950-988 (registration)

  Maps the string 'updateEncounter' to the imported handler function in toolMapping object used by the CallToolRequest 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/encounterUtils.ts:136-141 (helper)

  TypeScript interface defining the arguments for updateEncounter, extending partial Encounter while omitting resourceType and id, with extra classCode convenience field.
  export interface UpdateEncounterArgs extends Omit<Partial<Encounter>, 'resourceType' | 'id'> { // If specific simplified fields are needed, they can be added here, // but Partial<Encounter> provides flexibility. // Example: classCode?: string; to simplify updating class via a code. classCode?: string; // Added for convenience - will be converted to Coding }