Medplum MCP Server

Instructions

Implementation Reference

• src/tools/medicationRequestUtils.ts:243-288 (handler)

  The core handler function that builds FHIR search parameters from input args and executes the search using medplum.searchResources.

  export async function searchMedicationRequests(args: SearchMedicationRequestsArgs): Promise<MedicationRequest[]> {
    await ensureAuthenticated();
    const searchCriteria: string[] = [];
  
    if (Object.keys(args).length === 0) {
      console.warn('MedicationRequest search called with no specific criteria. This might return a large number of results or be inefficient.');
    }
  
    if (args.patientId) {
      searchCriteria.push(`patient=Patient/${args.patientId}`);
    }
    if (args.status) {
      searchCriteria.push(`status=${args.status}`);
    }
    if (args.intent) {
      searchCriteria.push(`intent=${args.intent}`);
    }
    if (args.code) {
      searchCriteria.push(`code=${args.code}`);
    }
    if (args.authoredon) {
      searchCriteria.push(`authoredon=${args.authoredon}`);
    }
    if (args.requester) {
      searchCriteria.push(`requester=${args.requester}`);
    }
    if (args.identifier) {
      searchCriteria.push(`identifier=${args.identifier}`);
    }
    if (args._lastUpdated) {
      searchCriteria.push(`_lastUpdated=${args._lastUpdated}`);
    }
  
    if (searchCriteria.length === 0 && Object.keys(args).length > 0) {
      console.warn('MedicationRequest search arguments provided but did not map to any known search parameters:', args);
      return [];
    }
    
    // Only search if there are criteria or if no arguments were provided (search all)
    if (searchCriteria.length > 0 || Object.keys(args).length === 0) {
        const queryString = searchCriteria.join('&');
        return medplum.searchResources('MedicationRequest', queryString);
    } else {
        return []; // Should be caught by the warning above, but as a fallback
    }
  } 

• src/tools/medicationRequestUtils.ts:52-63 (schema)

  TypeScript interface defining the input arguments for the searchMedicationRequests function.

  export interface SearchMedicationRequestsArgs {
    patientId?: string; // Searches for subject=Patient/[patientId]
    status?: MedicationRequest['status'];
    intent?: MedicationRequest['intent'];
    code?: string; // Searches by medicationCodeableConcept.coding.code
    codeSystem?: string; // System for the medication code
    authoredon?: string; // Date search for authoredOn, supports prefixes like eq, gt, le
    requester?: string; // FHIR style search param: Practitioner/XYZ or Organization/XYZ
    identifier?: string; // Search by identifier value (e.g. value or system|value)
    _lastUpdated?: string;
    // Add other common search parameters
  }

• src/index.ts:627-653 (registration)

  MCP tool registration in the mcpTools array, including name, description, and inputSchema.

  {
    name: "searchMedicationRequests",
    description: "Searches for medication requests based on criteria like patient ID or medication.",
    inputSchema: {
      type: "object",
      properties: {
        patientId: {
          type: "string",
          description: "The patient ID to search medication requests for. Optional.",
        },
        medicationReference: {
          type: "string",
          description: "The medication reference to filter by. Optional.",
        },
        practitionerId: {
          type: "string",
          description: "The practitioner ID to search medication requests for. Optional.",
        },
        status: {
          type: "string",
          description: "The medication request status to filter by. Optional.",
          enum: ["active", "on-hold", "cancelled", "completed", "entered-in-error", "stopped", "draft", "unknown"],
        },
      },
      required: [],
    },
  },

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

  Mapping of tool name to handler function for execution in the MCP server.

  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,
  };