Medplum MCP Server

Instructions

Implementation Reference

• src/tools/conditionUtils.ts:127-187 (handler)

  The core handler function that executes the tool logic: validates args, constructs FHIR Condition resource, creates it via Medplum client, handles errors with OperationOutcome.
  export async function createCondition( args: CreateConditionArgs, client?: MedplumClient, ): Promise<Condition | OperationOutcome> { const medplumClient = client || medplum; await ensureAuthenticated(); try { if (!args.subject || !args.subject.reference) { throw new Error('Patient subject reference is required.'); } if (!args.code || !args.code.coding || args.code.coding.length === 0) { throw new Error('Condition code with at least one coding is required.'); } const conditionResource: Condition = { resourceType: 'Condition', subject: args.subject, code: args.code, clinicalStatus: args.clinicalStatus || { coding: [ConditionClinicalStatusCodes.ACTIVE] }, verificationStatus: args.verificationStatus || { coding: [ConditionVerificationStatusCodes.CONFIRMED] }, category: args.category, encounter: args.encounter, onsetDateTime: args.onsetDateTime, onsetAge: args.onsetAge, onsetPeriod: args.onsetPeriod, onsetString: args.onsetString, recordedDate: args.recordedDate, asserter: args.asserter, }; // Remove undefined fields to create a clean resource object Object.keys(conditionResource).forEach( (key) => (conditionResource as any)[key] === undefined && delete (conditionResource as any)[key], ); const createdCondition = (await medplumClient.createResource( conditionResource, )) as Condition; console.log('Condition created successfully:', createdCondition.id); return createdCondition; } catch (error: any) { console.error('Error creating Condition:', error); const outcome: OperationOutcome = { resourceType: 'OperationOutcome', issue: [ { severity: 'error', code: 'exception', diagnostics: `Error creating Condition: ${error.message || 'Unknown error'}`, }, ], }; if (error.outcome) { console.error('Server OperationOutcome:', JSON.stringify(error.outcome, null, 2)); return error.outcome as OperationOutcome; } return outcome; } }
• src/tools/conditionUtils.ts:88-101 (schema)

  TypeScript interface defining the input arguments for the createCondition handler.
  export interface CreateConditionArgs { subject: Reference<Patient>; code: CodeableConcept; clinicalStatus?: CodeableConcept; verificationStatus?: CodeableConcept; category?: CodeableConcept[]; encounter?: Reference<Encounter>; onsetDateTime?: string; onsetAge?: Age; onsetPeriod?: Period; onsetString?: string; recordedDate?: string; // ISO 8601 date string asserter?: Reference<Patient | Practitioner>; }
• src/tools/toolSchemas.ts:700-754 (schema)

  JSON schema definition for the createCondition tool input, used in tool registry.
  name: 'createCondition', description: 'Creates a new condition or diagnosis for a patient. Requires a patient ID and a condition code.', input_schema: { type: 'object', properties: { patientId: { type: 'string', description: 'The ID of the patient for whom the condition is being created.', }, code: { type: 'object', description: 'The code representing the condition. Must include a coding system, code, and display text.', properties: { coding: { type: 'array', items: { type: 'object', properties: { system: { type: 'string', description: 'The URI of the coding system (e.g., "http://snomed.info/sct").', }, code: { type: 'string', description: 'The code from the system (e.g., "44054006").' }, display: { type: 'string', description: 'The human-readable display text for the code (e.g., "Type 2 diabetes mellitus").', }, }, required: ['system', 'code', 'display'], }, }, text: { type: 'string', description: 'A human-readable summary of the condition.' }, }, required: ['coding', 'text'], }, clinicalStatus: { type: 'string', description: 'The clinical status of the condition. For example: "active", "inactive", "resolved".', enum: ['active', 'recurrence', 'relapse', 'inactive', 'remission', 'resolved'], }, onsetString: { type: 'string', description: 'Estimated date, state, or age when the condition began (e.g., "about 3 years ago"). Optional.', }, recordedDate: { type: 'string', description: 'The date the condition was recorded, in YYYY-MM-DD format. Optional.', }, }, required: ['patientId', 'code'], },
• src/index.ts:950-988 (registration)

  Tool mapping registry that associates the 'createCondition' string name with the imported handler function for dispatching.
  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:1046-1060 (registration)

  Special dispatching logic in the MCP server request handler that adapts LLM-provided args to the handler's expected CreateConditionArgs format.
  } else if (toolName === 'createCondition') { // Special handling for createCondition const { patientId, code, clinicalStatus, onsetString, recordedDate } = args; const createArgs: any = { subject: { reference: `Patient/${patientId}` }, code, onsetString, recordedDate, }; if (clinicalStatus) { const key = (clinicalStatus as string).toUpperCase() as keyof typeof ConditionClinicalStatusCodes; createArgs.clinicalStatus = { coding: [ConditionClinicalStatusCodes[key]] }; } result = await toolFunction(createArgs); } else if (toolName === 'searchConditions') {