Medplum MCP Server

Instructions

Implementation Reference

• src/tools/medicationUtils.ts:84-127 (handler)

  The core handler function that implements the getMedicationById tool. It uses MedplumClient to read the Medication resource by ID, handles authentication, not-found cases (returns null), and errors (returns OperationOutcome).

  /**
   * Retrieves a Medication resource by its ID.
   * @param medicationId The ID of the Medication to retrieve.
   * @returns The Medication resource or null if not found, or an OperationOutcome on error.
   */
  export async function getMedicationById(
    medicationId: string,
    client?: MedplumClient,
  ): Promise<Medication | null | OperationOutcome> {
    const medplumClient = client || medplum;
    await ensureAuthenticated();
    try {
      if (!medicationId) {
        throw new Error('Medication ID is required.');
      }
      const medication = (await medplumClient.readResource(
        'Medication',
        medicationId,
      )) as Medication | null;
      console.log('Medication retrieved:', medication);
      return medication;
    } catch (error: any) {
      if (error.outcome && error.outcome.issue && error.outcome.issue[0]?.code === 'not-found') {
        console.log(`Medication with ID "${medicationId}" not found.`);
        return null;
      }
      console.error(`Error retrieving Medication with ID "${medicationId}":`, error);
      const outcome: OperationOutcome = {
        resourceType: 'OperationOutcome',
        issue: [
          {
            severity: 'error',
            code: 'exception',
            diagnostics: `Error retrieving Medication: ${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/index.ts:678-690 (schema)

  MCP tool schema definition for getMedicationById, specifying input as medicationId string.

    name: "getMedicationById",
    description: "Retrieves a medication by its unique ID.",
    inputSchema: {
      type: "object",
      properties: {
        medicationId: {
          type: "string",
          description: "The unique ID of the medication to retrieve.",
        },
      },
      required: ["medicationId"],
    },
  },

• src/index.ts:950-988 (registration)

  Registration of the getMedicationById handler function in the toolMapping object used by the MCP server to dispatch tool calls.

  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:51-54 (registration)

  Import statement bringing the getMedicationById function into index.ts for registration.

    createMedication,
    getMedicationById,
    searchMedications,
  } from './tools/medicationUtils.js';

• src/tools/toolSchemas.ts:518-527 (schema)

  Alternative or legacy schema definition for getMedicationById tool (note: input_schema vs inputSchema, may not be actively used).

    name: 'getMedicationById',
    description: 'Retrieves a Medication resource by its unique ID.',
    input_schema: {
      type: 'object',
      properties: {
        medicationId: { type: 'string', description: 'The unique ID of the Medication to retrieve.' },
      },
      required: ['medicationId'],
    },
  },