Medplum MCP Server

Instructions

Implementation Reference

• src/tools/conditionUtils.ts:295-362 (handler)

  The primary handler function that performs a FHIR search for Condition resources using the Medplum client. It constructs search criteria from input arguments (patient/subject, category, clinical-status, code, asserter.identifier) and returns matching Conditions or an OperationOutcome on error.

  export async function searchConditions(
    args: ConditionSearchArgs,
    client?: MedplumClient,
  ): Promise<Condition[] | OperationOutcome> {
    const medplumClient = client || medplum;
    await ensureAuthenticated();
    try {
      const searchCriteria: string[] = [];
      const patientId = args.subject || args.patient;
  
      if (patientId) {
        // Medplum search needs the full reference, but the arg might just be an ID
        searchCriteria.push(`subject=${patientId.startsWith('Patient/') ? patientId : `Patient/${patientId}`}`);
      }
      if (args.category) {
        searchCriteria.push(`category=${args.category}`);
      }
      if (args['clinical-status']) {
        searchCriteria.push(`clinical-status=${args['clinical-status']}`);
      }
      if (args.code) {
        searchCriteria.push(`code=${args.code}`);
      }
      if(args['asserter.identifier']){
        searchCriteria.push(`asserter.identifier=${args['asserter.identifier']}`);
      }
  
      if (searchCriteria.length === 0) {
        return {
          resourceType: 'OperationOutcome',
          issue: [
            {
              severity: 'error',
              code: 'invalid',
              diagnostics:
                'At least one search criterion (subject, patient, category, clinical-status, or code) must be provided.',
            },
          ],
        };
      }
  
      const query = searchCriteria.join('&');
      console.log('Searching conditions with query:', query);
  
      const searchResult = await medplumClient.searchResources('Condition', query);
      const conditions = searchResult as Condition[];
  
      console.log(`Found ${conditions.length} conditions.`);
      return conditions;
    } catch (error: any) {
      console.error('Error searching Conditions:', error);
      const outcome: OperationOutcome = {
        resourceType: 'OperationOutcome',
        issue: [
          {
            severity: 'error',
            code: 'exception',
            diagnostics: `Error searching Conditions: ${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/tools/toolSchemas.ts:798-824 (schema)

  Input schema definition for the searchConditions tool, specifying parameters like patientId (required), code, clinical-status, and category.

  {
    name: 'searchConditions',
    description: 'Searches for conditions based on patient and other criteria. Requires a patient ID.',
    input_schema: {
      type: 'object',
      properties: {
        patientId: {
          type: 'string',
          description: "The ID of the patient whose conditions are being searched.",
        },
        code: {
          type: 'string',
          description: 'A code to filter by, e.g., "http://snomed.info/sct|44054006". Optional.',
        },
        'clinical-status': {
          type: 'string',
          description: 'Filter by clinical status.',
          enum: ['active', 'recurrence', 'relapse', 'inactive', 'remission', 'resolved'],
        },
        category: {
          type: 'string',
          description: 'Filter by category, e.g., "encounter-diagnosis" or "problem-list-item".',
        },
      },
      required: ['patientId'],
    },
  },

• src/index.ts:893-919 (registration)

  Registration of the searchConditions tool in the MCP server's tool list (mcpTools array), including its schema for the listTools handler.

  {
    name: "searchConditions",
    description: "Searches for conditions based on patient and other criteria. Requires a patient ID.",
    inputSchema: {
      type: "object",
      properties: {
        patientId: {
          type: "string",
          description: "The ID of the patient whose conditions are being searched.",
        },
        code: {
          type: "string",
          description: "A code to filter by, e.g., \"http://snomed.info/sct|44054006\". Optional.",
        },
        "clinical-status": {
          type: "string",
          description: "Filter by clinical status.",
          enum: ["active", "recurrence", "relapse", "inactive", "remission", "resolved"],
        },
        category: {
          type: "string",
          description: "Filter by category, e.g., \"encounter-diagnosis\" or \"problem-list-item\".",
        },
      },
      required: ["patientId"],
    },
  },

• src/index.ts:1060-1066 (registration)

  Special dispatching logic in the MCP callTool handler that maps 'patientId' from arguments to 'subject' for the searchConditions function call.

  } else if (toolName === 'searchConditions') {
    // Special handling for searchConditions
    const { patientId, ...searchArgs } = args;
    if (patientId) {
      searchArgs.subject = patientId;
    }
    result = await toolFunction(searchArgs);

• src/tools/conditionUtils.ts:113-120 (helper)

  TypeScript interface defining the input arguments for the searchConditions function.

  export interface ConditionSearchArgs {
    subject?: string; // Patient ID
    patient?: string; // Patient ID (alternative to subject)
    category?: string; // e.g., 'encounter-diagnosis'
    'clinical-status'?: string; // e.g., 'active'
    code?: string; // e.g., 'http://snomed.info/sct|44054006'
    'asserter.identifier'?: string;
  }