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
  }