Medplum MCP Server

Instructions

Implementation Reference

• src/tools/observationUtils.ts:91-163 (handler)

  The main handler function that implements the createObservation tool logic. It constructs an Observation FHIR resource from the input arguments, performs validations, handles ID-to-reference conversions, and calls medplum.createResource to persist it.
  export async function createObservation(args: CreateObservationArgs): Promise<Observation> { await ensureAuthenticated(); // Handle subjectId conversion for convenience let subject = args.subject; if (args.subjectId && !subject) { subject = { reference: `Patient/${args.subjectId}` }; } // Handle encounterId conversion for convenience let encounter = args.encounter; if (args.encounterId && !encounter) { encounter = { reference: `Encounter/${args.encounterId}` }; } // Handle performerIds conversion for convenience let performer = args.performer; if (args.performerIds && !performer) { performer = args.performerIds.map(id => ({ reference: `Practitioner/${id}` })); } if (!subject?.reference) { throw new Error('Patient reference is required to create an observation.'); } if (!args.code || !args.code.coding || args.code.coding.length === 0) { throw new Error('Observation code with at least one coding is required.'); } if (!args.status) { throw new Error('Observation status is required.'); } if ( args.valueQuantity === undefined && args.valueCodeableConcept === undefined && args.valueString === undefined && args.valueBoolean === undefined && args.valueInteger === undefined && args.valueRange === undefined && args.valueRatio === undefined && args.valueSampledData === undefined && args.valueTime === undefined && args.valueDateTime === undefined && args.valuePeriod === undefined ) { throw new Error('At least one value field must be provided (valueQuantity, valueCodeableConcept, valueString, valueBoolean, valueInteger, valueRange, valueRatio, valueSampledData, valueTime, valueDateTime, or valuePeriod).'); } const observationResource: Observation = { resourceType: 'Observation', status: args.status, code: args.code, subject: subject, encounter: encounter, effectiveDateTime: args.effectiveDateTime, effectivePeriod: args.effectivePeriod, issued: args.issued || new Date().toISOString(), performer: performer, valueQuantity: args.valueQuantity, valueCodeableConcept: args.valueCodeableConcept, valueString: args.valueString, valueBoolean: args.valueBoolean, valueInteger: args.valueInteger, valueRange: args.valueRange, valueRatio: args.valueRatio, valueSampledData: args.valueSampledData, valueTime: args.valueTime, valueDateTime: args.valueDateTime, valuePeriod: args.valuePeriod, bodySite: args.bodySite, method: args.method, referenceRange: args.referenceRange, note: args.note ? [{ text: args.note }] : undefined, interpretation: args.interpretation, identifier: args.identifier ? [{ system: args.identifier.system, value: args.identifier.value }] : undefined, }; if (args.component) { observationResource.component = args.component; } return medplum.createResource<Observation>(observationResource); }
• src/tools/observationUtils.ts:5-35 (schema)

  TypeScript interface defining the input arguments for the createObservation function, providing type safety and documentation for the expected parameters.
  export interface CreateObservationArgs { status: Observation['status']; code: CodeableConcept; subject?: Reference<Patient>; // Made optional since tests use subjectId subjectId?: string; // For convenience in tests - will be converted to subject reference encounter?: Reference<Encounter>; encounterId?: string; // For convenience in tests - will be converted to encounter reference effectiveDateTime?: string; effectivePeriod?: Period; issued?: string; performer?: Reference<Practitioner>[]; performerIds?: string[]; // For convenience in tests - will be converted to performer references valueQuantity?: Quantity; valueString?: string; valueBoolean?: boolean; valueCodeableConcept?: CodeableConcept; valueInteger?: number; valueRange?: Range; valueRatio?: Ratio; valueSampledData?: SampledData; valueTime?: string; valueDateTime?: string; valuePeriod?: Period; bodySite?: CodeableConcept; method?: CodeableConcept; component?: any[]; interpretation?: CodeableConcept[]; note?: string; referenceRange?: any[]; identifier?: { system?: string; value: string }; }
• src/index.ts:459-492 (registration)

  MCP tool registration including the name, description, and input schema for the createObservation tool, used by the ListToolsRequest handler.
  name: "createObservation", description: "Creates a new observation (lab result, vital sign, etc.). Requires patient ID and code.", inputSchema: { type: "object", properties: { patientId: { type: "string", description: "The ID of the patient this observation is for.", }, code: { type: "string", description: "The code representing what was observed (LOINC, SNOMED CT, etc.).", }, valueQuantity: { type: "number", description: "Numeric value of the observation. Optional.", }, valueString: { type: "string", description: "String value of the observation. Optional.", }, status: { type: "string", description: "The status of the observation.", enum: ["registered", "preliminary", "final", "amended", "corrected", "cancelled"], }, encounterId: { type: "string", description: "The encounter this observation is associated with. Optional.", }, }, required: ["patientId", "code", "status"], }, },
• src/index.ts:968-968 (registration)

  Mapping of the createObservation function to the tool name in the toolMapping object, used by the CallToolRequest handler to execute the tool.
  createObservation,
• src/index.ts:39-43 (registration)

  Import statement bringing the createObservation handler into the main index file for registration.
  createObservation, getObservationById, updateObservation, searchObservations, } from './tools/observationUtils.js';