Medplum MCP Server

Instructions

Implementation Reference

• src/tools/episodeOfCareUtils.ts:62-120 (handler)

  Implements the core logic for creating an EpisodeOfCare FHIR resource using the Medplum client, including validation, resource construction, and error handling.
  export async function createEpisodeOfCare( args: CreateEpisodeOfCareArgs, client?: MedplumClient, ): Promise<EpisodeOfCare | OperationOutcome> { const medplumClient = client || medplum; await ensureAuthenticated(); try { if (!args.patientId) { throw new Error('Patient ID is required to create an EpisodeOfCare.'); } if (!args.status) { throw new Error('Status is required to create an EpisodeOfCare.'); } const episode: EpisodeOfCare = { resourceType: 'EpisodeOfCare', status: args.status, patient: { reference: `Patient/${args.patientId}` }, type: args.type, identifier: args.identifier, period: args.periodStart || args.periodEnd ? { start: args.periodStart, end: args.periodEnd, } : undefined, managingOrganization: args.managingOrganizationId ? { reference: `Organization/${args.managingOrganizationId}` } : undefined, careManager: args.careManagerId ? { reference: `Practitioner/${args.careManagerId}` } : undefined, // team: args.teamMemberIds?.map(id => ({ reference: `CareTeam/${id}` })) // If using CareTeam IDs }; // Remove undefined top-level fields to keep the resource clean Object.keys(episode).forEach((key) => (episode as any)[key] === undefined && delete (episode as any)[key]); if (episode.period && !episode.period.start && !episode.period.end) { delete episode.period; } const result = (await medplumClient.createResource(episode)) as EpisodeOfCare; console.log('EpisodeOfCare created successfully:', result.id); return result; } catch (error: any) { const outcome: OperationOutcome = { resourceType: 'OperationOutcome', issue: [ { severity: 'error', code: 'exception', diagnostics: `Error creating EpisodeOfCare: ${error.message || 'Unknown error'}`, }, ], }; if (error.outcome) { return error.outcome as OperationOutcome; } return outcome; } }
• src/tools/toolSchemas.ts:552-606 (schema)

  Defines the JSON schema for input validation of the createEpisodeOfCare tool, including parameters like patientId, status, and optional fields.
  { name: 'createEpisodeOfCare', description: 'Creates a new EpisodeOfCare for a patient. Requires patient ID and status.', input_schema: { type: 'object', properties: { patientId: { type: 'string', description: "The ID of the patient for whom this episode of care is being created." }, status: { type: 'string', description: "The status of the episode of care.", enum: ['planned', 'waitlist', 'active', 'onhold', 'finished', 'cancelled', 'entered-in-error'] }, managingOrganizationId: { type: 'string', description: "Optional. ID of the organization managing this episode of care." }, careManagerId: { type: 'string', description: "Optional. ID of the practitioner who is the care manager for this episode." }, type: { type: 'array', items: { type: 'object', properties: { coding: { type: 'array', items: { type: 'object', properties: { system: { type: 'string', description: "The URI for the coding system (e.g., 'http://terminology.hl7.org/CodeSystem/episodeofcare-type')." }, code: { type: 'string', description: "The code from the coding system (e.g., 'hacc')." }, display: { type: 'string', description: "Optional. The display name for the code." } }, required: ['system', 'code'] } }, text: { type: 'string', description: "Optional. Plain text representation of the type." } }, // required: ['coding'] // A type can be just text }, description: "Optional. Type of episode of care, e.g., Home and Community Care. Provide an array of CodeableConcept objects." }, periodStart: { type: 'string', format: 'date-time', description: "Optional. The start date/time of the episode of care (ISO8601 format)." }, periodEnd: { type: 'string', format: 'date-time', description: "Optional. The end date/time of the episode of care (ISO8601 format)." }, identifier: { type: 'array', items: { type: 'object', properties: { system: { type: 'string', description: "The system for the identifier (e.g., 'urn:oid:1.2.3.4.5')." }, value: { type: 'string', description: "The value of the identifier." } }, required: ['value'] }, description: "Optional. One or more identifiers for this episode of care." } }, required: ['patientId', 'status'] } },
• src/index.ts:714-736 (registration)

  Registers the createEpisodeOfCare tool in the MCP server by including its schema in the mcpTools array used for list tools request.
  { name: "createEpisodeOfCare", description: "Creates a new episode of care for a patient. Requires patient ID and status.", inputSchema: { type: "object", properties: { patientId: { type: "string", description: "The ID of the patient this episode of care is for.", }, status: { type: "string", description: "The status of the episode of care.", enum: ["planned", "waitlist", "active", "onhold", "finished", "cancelled", "entered-in-error"], }, managingOrganizationId: { type: "string", description: "The ID of the organization managing this episode. Optional.", }, }, required: ["patientId", "status"], }, },
• src/index.ts:979-979 (registration)

  Maps the tool name to its handler function in the toolMapping object used by the MCP call tool request handler.
  createEpisodeOfCare,
• src/tools/episodeOfCareUtils.ts:26-37 (schema)

  TypeScript interface defining the arguments for the createEpisodeOfCare function, used for type safety in the handler.
  export interface CreateEpisodeOfCareArgs { patientId: string; status: EpisodeOfCareStatus; // planned | waitlist | active | onhold | finished | cancelled | entered-in-error managingOrganizationId?: string; type?: CodeableConcept[]; // e.g., [{ coding: [{ system: 'http://terminology.hl7.org/CodeSystem/episodeofcare-type', code: 'hacc' }]}] (Home and Community Care) periodStart?: string; // ISO8601 DateTime periodEnd?: string; // ISO8601 DateTime careManagerId?: string; // ID of the Practitioner teamMemberIds?: string[]; // IDs of CareTeam resources (more complex, consider if needed for initial version) identifier?: Identifier[]; // diagnosis related fields are complex (condition, role, rank) - might simplify or add later }