Medplum MCP Server

Instructions

Implementation Reference

• src/tools/observationUtils.ts:328-382 (handler)

  The core handler function that implements the searchObservations tool logic. It authenticates, builds FHIR search parameters from input args, and performs the search using medplum.searchResources.
  export async function searchObservations(args: ObservationSearchArgs): Promise<Observation[]> { await ensureAuthenticated(); const searchCriteria: string[] = []; if (Object.keys(args).length === 0) { console.warn('Observation search called with no specific criteria. This might return a large number of results or be inefficient.'); } if (args.patientId) { searchCriteria.push(`subject=Patient/${args.patientId}`); } else if (args.subject) { searchCriteria.push(`subject=${args.subject}`); } if (args.code) { if (args.codeSystem) { searchCriteria.push(`code=${args.codeSystem}|${args.code}`); } else { searchCriteria.push(`code=${args.code}`); } } if (args.encounterId) { searchCriteria.push(`encounter=Encounter/${args.encounterId}`); } if (args.date) { // If no comparator is provided, default to 'eq' for exact date match const dateValue = args.date.match(/^(eq|ne|gt|lt|ge|le)/) ? args.date : `eq${args.date}`; searchCriteria.push(`date=${dateValue}`); } if (args.status) { searchCriteria.push(`status=${args.status}`); } if (args.performer) { searchCriteria.push(`performer=${args.performer}`); } 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('Observation search arguments provided but did not map to any known search parameters:', args); return []; } if (searchCriteria.length > 0 || Object.keys(args).length === 0) { const queryString = searchCriteria.join('&'); // console.log(`Searching observations with query: ${queryString}`); // Optional: for debugging return medplum.searchResources('Observation', queryString); } else { return []; } }
• src/tools/observationUtils.ts:72-83 (schema)

  TypeScript interface defining the input parameters accepted by the searchObservations handler.
  export interface ObservationSearchArgs { patientId?: string; code?: string; // Search by LOINC or other code system code codeSystem?: string; // Specify the system for the code encounterId?: string; date?: string; // Search by effectiveDateTime or effectivePeriod status?: Observation['status']; subject?: string; // FHIR style search param: Patient/XYZ performer?: string; // FHIR style search param: Practitioner/XYZ identifier?: string; // Search by identifier value (e.g. value or system|value) _lastUpdated?: string; // Search by last updated date }
• src/index.ts:534-560 (schema)

  MCP protocol input schema definition for the searchObservations tool, used for validation and tool listing.
  { name: "searchObservations", description: "Searches for observations based on criteria like patient ID or code.", inputSchema: { type: "object", properties: { patientId: { type: "string", description: "The patient ID to search observations for. Optional.", }, code: { type: "string", description: "The observation code to filter by. Optional.", }, status: { type: "string", description: "The observation status to filter by. Optional.", enum: ["registered", "preliminary", "final", "amended", "corrected", "cancelled"], }, encounterId: { type: "string", description: "The encounter ID to search observations for. Optional.", }, }, required: [], }, },
• src/index.ts:950-988 (registration)

  The toolMapping object registers 'searchObservations' by mapping the tool name to its imported handler function, used by the MCP server request handler to dispatch 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:39-44 (registration)

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