searchEncounters
Search and filter healthcare encounters by patient ID, practitioner ID, or status on the Medplum MCP Server. Retrieve relevant encounter data efficiently for improved care coordination.
Instructions
Searches for encounters based on criteria like patient ID or status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| patientId | No | The patient ID to search encounters for. Optional. | |
| practitionerId | No | The practitioner ID to search encounters for. Optional. | |
| status | No | The encounter status to filter by. Optional. |
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 }