Medplum MCP Server

Instructions

Implementation Reference

• src/tools/generalFhirSearchUtils.ts:15-90 (handler)

  The core handler function that executes the general FHIR search logic using the Medplum client. It constructs the query string from provided parameters and performs the search, handling errors with OperationOutcome.
  export async function generalFhirSearch( args: GeneralFhirSearchArgs, client?: MedplumClient, ): Promise<Bundle<Resource> | OperationOutcome> { const medplumClient = client || medplum; await ensureAuthenticated(); try { if (!args.resourceType) { return { resourceType: 'OperationOutcome', issue: [ { severity: 'error', code: 'invalid', diagnostics: 'Resource type is required for general FHIR search.', }, ], }; } if (!args.queryParams || Object.keys(args.queryParams).length === 0) { return { resourceType: 'OperationOutcome', issue: [ { severity: 'error', code: 'invalid', diagnostics: 'At least one query parameter is required for general FHIR search.', }, ], }; } // Construct the query string from queryParams const queryString = Object.entries(args.queryParams) .map(([key, value]) => { if (Array.isArray(value)) { // For _id, comma-separate: field=_id=v1,v2,v3 if (key === '_id') { return `${encodeURIComponent(key)}=${value.map(v => String(v)).join(',')}`; } // For other array values, create multiple parameters: key=v1&key=v2 return value.map(v => `${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`).join('&'); } return `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`; }) .join('&'); console.log(`Performing general FHIR search for type "${args.resourceType}" with query: ${queryString}`); // Medplum SDK's search method can take ResourceType or a string for the resource type. // The result is a Bundle of the specified Resource type. const result = (await medplumClient.search(args.resourceType as ResourceType, queryString)) as Bundle<Resource>; console.log(`General FHIR search found ${result.entry?.length || 0} resources.`); return result; } catch (error: any) { console.error(`Error during general FHIR search for type "${args.resourceType}":`, error); if (error.outcome) { // Prefer the outcome from the error if available return error.outcome as OperationOutcome; } // Fallback to a generic OperationOutcome return { resourceType: 'OperationOutcome', issue: [ { severity: 'error', code: 'exception', diagnostics: `Error during general FHIR search: ${error.message || 'Unknown error'}`, }, ], }; } }
• src/tools/toolSchemas.ts:665-697 (schema)

  JSON Schema definition for the generalFhirSearch tool input, defining resourceType and queryParams with detailed descriptions and examples.
  name: 'generalFhirSearch', description: 'Performs a generic search for any FHIR resource type using specified query parameters. Useful when the exact resource type is known and specific search criteria need to be applied, or for resource types not covered by other specialized tools.', input_schema: { type: 'object', properties: { resourceType: { type: 'string', description: "The FHIR resource type to search for (e.g., 'Patient', 'Observation', 'MedicationRequest'). This must be a valid FHIR resource type name.", // Potentially add an enum of common ResourceTypes if helpful for LLM, but can be very long. // Example enum (partial): enum: ['Patient', 'Practitioner', 'Organization', 'Encounter', 'Observation', 'MedicationRequest', 'Condition', 'Procedure', 'DiagnosticReport'] }, queryParams: { type: 'object', description: "An object where keys are FHIR search parameters (e.g., 'name', 'date', '_id', 'patient') and values are the corresponding search values. For parameters that can appear multiple times (like 'date' for a range), provide an array of strings as the value (e.g., { date: ['ge2023-01-01', 'le2023-01-31'] }). For token parameters (codeableConcepts), provide the value as 'system|code' or just 'code'. For reference parameters, use 'ResourceType/id' or just 'id'.", additionalProperties: { oneOf: [ { type: 'string' }, { type: 'number' }, { type: 'boolean' }, { type: 'array', items: { type: 'string' } } ] }, example: { _id: "12345", status: "active", "patient.name": "John Doe", date: ["ge2024-01-01", "le2024-01-31"] } } }, required: ['resourceType', 'queryParams'] } },
• src/index.ts:922-946 (registration)

  MCP tool registration in the mcpTools array, including schema and description for the generalFhirSearch tool.
  name: "generalFhirSearch", description: "Performs a generic FHIR search operation on any resource type with custom query parameters.", inputSchema: { type: "object", properties: { resourceType: { type: "string", description: "The FHIR resource type to search for (e.g., 'Patient', 'Observation').", }, queryParams: { type: "object", description: "A record of query parameters, where keys are FHIR search parameters and values are their corresponding values.", additionalProperties: { oneOf: [ { type: "string" }, { type: "number" }, { type: "boolean" }, { type: "array", items: { type: "string" } } ] }, }, }, required: ["resourceType", "queryParams"], }, },
• src/index.ts:70-71 (registration)

  Import statement bringing the generalFhirSearch handler function into the main index file.
  generalFhirSearch, } from './tools/generalFhirSearchUtils.js';
• src/index.ts:987-987 (registration)

  Mapping of the tool name to its handler function in the toolMapping object used for execution.
  generalFhirSearch,