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 {