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
  }