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') {