Medplum MCP Server

Instructions

Implementation Reference

• src/tools/encounterUtils.ts:213-253 (handler)

  The core handler function that executes the FHIR search for Encounter resources using Medplum's searchResources method, building query parameters from input arguments.

  export async function searchEncounters(searchArgs: EncounterSearchArgs): Promise<Encounter[]> {
    await ensureAuthenticated();
    
    const searchCriteria: string[] = [];
  
    if (searchArgs.patientId) {
      searchCriteria.push(`subject=Patient/${searchArgs.patientId}`);
    }
    if (searchArgs.practitionerId) {
      const practitionerRef = searchArgs.practitionerId.startsWith('Practitioner/') 
        ? searchArgs.practitionerId 
        : `Practitioner/${searchArgs.practitionerId}`;
      searchCriteria.push(`participant=${practitionerRef}`);
    }
    if (searchArgs.organizationId) {
      searchCriteria.push(`service-provider=Organization/${searchArgs.organizationId}`);
    }
    if (searchArgs.status) {
      searchCriteria.push(`status=${searchArgs.status}`);
    }
    if (searchArgs.classCode) {
      searchCriteria.push(`class=${searchArgs.classCode}`);
    }
    if (searchArgs.date) {
      searchCriteria.push(`date=${searchArgs.date}`);
    }
    if (searchArgs.identifier) {
      searchCriteria.push(`identifier=${searchArgs.identifier}`);
    }
    if (searchArgs._lastUpdated) {
      searchCriteria.push(`_lastUpdated=${searchArgs._lastUpdated}`);
    }
  
    if (searchCriteria.length === 0) {
      console.warn('Encounter search called with no specific criteria. This might return a large number of results or be inefficient.');
      return []; // Return empty array if no criteria are provided
    }
  
    const queryString = searchCriteria.join('&');
    return medplum.searchResources('Encounter', queryString);
  } 

• src/index.ts:434-456 (schema)

  MCP tool schema definition including input schema validation for the searchEncounters tool.

  {
    name: "searchEncounters",
    description: "Searches for encounters based on criteria like patient ID or status.",
    inputSchema: {
      type: "object",
      properties: {
        patientId: {
          type: "string",
          description: "The patient ID to search encounters for. Optional.",
        },
        status: {
          type: "string",
          description: "The encounter status to filter by. Optional.",
          enum: ["planned", "arrived", "triaged", "in-progress", "onleave", "finished", "cancelled"],
        },
        practitionerId: {
          type: "string",
          description: "The practitioner ID to search encounters for. Optional.",
        },
      },
      required: [],
    },
  },

• src/index.ts:36-36 (registration)

  Import of the searchEncounters handler function from encounterUtils for registration in the MCP server.

  searchEncounters,

• src/index.ts:967-967 (registration)

  Registration of searchEncounters in the toolMapping object used by the MCP CallToolRequest handler.

  searchEncounters,

• src/tools/encounterUtils.ts:191-205 (helper)

  Type definition for input arguments to the searchEncounters function.

  export interface EncounterSearchArgs {
    patientId?: string;
    subject?: string; // Added for FHIR-style search: Patient/123
    practitionerId?: string;
    participant?: string; // Added for FHIR-style search: Practitioner/456
    organizationId?: string;
    date?: string;
    status?: string;
    classCode?: string;
    typeCode?: string;
    typeSystem?: string; // Added for use with typeCode
    identifier?: string;
    _lastUpdated?: string; // Added for FHIR-style search
    // Add other common search parameters as needed
  }